add readme for running frontend
This commit is contained in:
DarrenT~
parent
b72331288a
commit
5e201cc033
412
README.md
412
README.md
@ -1,346 +1,144 @@
|
|||||||
# Fusero Boilerplate App
|
# Fusero App Boilerplate
|
||||||
|
|
||||||
This is a Fastify + MikroORM + PostgreSQL boilerplate, designed to run in Docker for local development.
|
A full-stack application boilerplate with React frontend and Node.js backend.
|
||||||
It is set up to run alongside other projects without port or database conflicts.
|
|
||||||
|
|
||||||
---
|
## Project Structure
|
||||||
|
|
||||||
## 1. Prerequisites
|
```
|
||||||
|
fusero-app-boilerplate/
|
||||||
- [Node.js](https://nodejs.org/) (v18+ recommended)
|
├── frontend/ # React frontend application
|
||||||
- [Docker](https://www.docker.com/get-started)
|
├── backend/ # Node.js backend application
|
||||||
- [npm](https://www.npmjs.com/)
|
├── docker-compose.yml # Production Docker configuration
|
||||||
|
└── docker-compose.dev.yml # Development Docker configuration
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Clone the Repo
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone <your-repo-url>
|
|
||||||
cd fusero-app-boilerplate
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
## Prerequisites
|
||||||
|
|
||||||
## 3. Setup the `.env` File
|
- Node.js (v18 or higher)
|
||||||
|
- npm (v9 or higher)
|
||||||
|
- Docker and Docker Compose
|
||||||
|
- Git
|
||||||
|
|
||||||
Copy `.env.example` to `.env` (or create `.env` if not present):
|
## Development Setup
|
||||||
|
|
||||||
```env
|
### Option 1: Running with Docker (Recommended for Development)
|
||||||
# Database connection for Docker
|
|
||||||
POSTGRES_NAME=fusero-boilerplate-db
|
|
||||||
POSTGRES_HOSTNAME=localhost
|
|
||||||
POSTGRES_PORT=19095
|
|
||||||
POSTGRES_USER=root
|
|
||||||
POSTGRES_PASSWORD=root123
|
|
||||||
|
|
||||||
# Test Database connection
|
1. **Start the Development Environment**
|
||||||
POSTGRES_TEST_NAME=test-db
|
```bash
|
||||||
POSTGRES_TEST_PORT=19096
|
docker-compose -f docker-compose.dev.yml up
|
||||||
|
```
|
||||||
|
This will start:
|
||||||
|
- Frontend on http://localhost:3000
|
||||||
|
- Backend on http://localhost:14000
|
||||||
|
- PostgreSQL database on port 19090
|
||||||
|
|
||||||
# Default admin user for seeding
|
### Option 2: Running Services Separately (Recommended for Debugging)
|
||||||
DEFAULT_ADMIN_USERNAME=darren
|
|
||||||
DEFAULT_ADMIN_EMAIL=darren@fusero.nl
|
|
||||||
DEFAULT_ADMIN_PASSWORD=admin123
|
|
||||||
|
|
||||||
# JWT secret
|
For better debugging experience, you can run the frontend and backend in separate terminal windows:
|
||||||
JWT_SECRET=your_jwt_secret_here
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. Start the Database (Docker)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker-compose -f docker-compose.dev.yml up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
This will start two Postgres instances:
|
|
||||||
- Main database on port 19095
|
|
||||||
- Test database on port 19096
|
|
||||||
|
|
||||||
Both with dedicated Docker volumes.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Install Dependencies
|
|
||||||
|
|
||||||
|
#### Terminal 1: Backend Service
|
||||||
```bash
|
```bash
|
||||||
|
cd backend
|
||||||
npm install
|
npm install
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Run Migrations
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run migration:create # Create a new migration
|
|
||||||
npm run migration:up # Run migrations
|
|
||||||
```
|
|
||||||
|
|
||||||
This will create all tables in the database.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Seed the Database
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run seed
|
|
||||||
```
|
|
||||||
|
|
||||||
This will create the default admin user and roles as specified in your `.env`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Start the App
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run dev
|
npm run dev
|
||||||
```
|
```
|
||||||
|
The backend will be available at http://localhost:14000
|
||||||
|
|
||||||
The app will be available at [http://localhost:14000](http://localhost:14000).
|
#### Terminal 2: Frontend Service
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. API Endpoints
|
|
||||||
|
|
||||||
### Authentication
|
|
||||||
|
|
||||||
#### Login
|
|
||||||
```bash
|
```bash
|
||||||
curl -X POST http://localhost:14000/api/v1/auth/login \
|
cd frontend
|
||||||
-H "Content-Type: application/json" \
|
npm install
|
||||||
-d '{
|
npm run dev
|
||||||
"username": "darren",
|
|
||||||
"password": "admin123"
|
|
||||||
}'
|
|
||||||
```
|
```
|
||||||
|
The frontend will be available at http://localhost:3000
|
||||||
|
|
||||||
Response:
|
### Environment Setup
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "Authentication successful",
|
|
||||||
"data": {
|
|
||||||
"token": "your.jwt.token",
|
|
||||||
"user": {
|
|
||||||
"id": 1,
|
|
||||||
"username": "darren",
|
|
||||||
"email": "darren@fusero.nl",
|
|
||||||
"roles": ["admin"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### User Management
|
1. **Backend Environment**
|
||||||
|
- Copy `.env.example` to `.env` in the backend directory
|
||||||
|
- Configure your environment variables:
|
||||||
|
```
|
||||||
|
PORT=14000
|
||||||
|
DB_HOST=localhost
|
||||||
|
DB_PORT=19090
|
||||||
|
DB_USER=postgres
|
||||||
|
DB_PASSWORD=postgres
|
||||||
|
DB_NAME=fusero
|
||||||
|
JWT_SECRET=your_jwt_secret_key_here
|
||||||
|
```
|
||||||
|
|
||||||
#### Create User
|
2. **Frontend Environment**
|
||||||
```bash
|
- Copy `.env.example` to `.env` in the frontend directory
|
||||||
curl -X POST http://localhost:14000/api/v1/app/users \
|
- Set the API base URL:
|
||||||
-H "Content-Type: application/json" \
|
```
|
||||||
-H "Authorization: Bearer your.jwt.token" \
|
VITE_API_BASE_URL=http://localhost:14000/api/v1
|
||||||
-d '{
|
```
|
||||||
"username": "newuser",
|
|
||||||
"password": "userpass123",
|
|
||||||
"email": "user@example.com",
|
|
||||||
"roleName": "user"
|
|
||||||
}'
|
|
||||||
```
|
|
||||||
|
|
||||||
Response:
|
## Production Deployment
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "User created successfully",
|
|
||||||
"data": {
|
|
||||||
"id": 2,
|
|
||||||
"username": "newuser",
|
|
||||||
"email": "user@example.com",
|
|
||||||
"roles": ["user"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Get All Users (Requires admin role)
|
1. **Build and Run with Docker**
|
||||||
```bash
|
```bash
|
||||||
curl -X GET http://localhost:14000/api/v1/app/users \
|
docker-compose up --build
|
||||||
-H "Authorization: Bearer your.jwt.token"
|
```
|
||||||
```
|
|
||||||
|
|
||||||
#### Get User by ID
|
2. **Environment Variables**
|
||||||
```bash
|
- Ensure all environment variables are properly set in your production environment
|
||||||
curl -X GET http://localhost:14000/api/v1/app/users/1 \
|
- Never commit `.env` files to version control
|
||||||
-H "Authorization: Bearer your.jwt.token"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Canvas Dummy Grades API
|
## Development Best Practices
|
||||||
|
|
||||||
The canvas API provides endpoints for managing dummy grades. All endpoints are prefixed with `/api/v1/canvas-api/`.
|
1. **Running Services Separately**
|
||||||
|
- For development, it's recommended to run frontend and backend in separate terminal windows
|
||||||
|
- This allows for better debugging and hot-reloading
|
||||||
|
- You can see logs from each service clearly
|
||||||
|
|
||||||
#### Get All Dummy Grades
|
2. **Code Organization**
|
||||||
```bash
|
- Frontend code should be in the `frontend/` directory
|
||||||
GET /api/v1/canvas-api/
|
- Backend code should be in the `backend/` directory
|
||||||
```
|
- Shared types and utilities should be in their respective directories
|
||||||
|
|
||||||
Response:
|
3. **Version Control**
|
||||||
```json
|
- Commit `package-lock.json` files
|
||||||
{
|
- Don't commit `.env` files
|
||||||
"success": true,
|
- Use meaningful commit messages
|
||||||
"message": "Dummy grades retrieved successfully",
|
|
||||||
"data": {
|
|
||||||
"grades": [
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"student_id": 101,
|
|
||||||
"course_id": 1,
|
|
||||||
"assignment_id": 1,
|
|
||||||
"score": 85,
|
|
||||||
"grade": "B",
|
|
||||||
"submitted_at": "2024-03-15T10:00:00Z",
|
|
||||||
"graded_at": "2024-03-16T14:30:00Z"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Add a New Dummy Grade
|
## API Documentation
|
||||||
```bash
|
|
||||||
POST /api/v1/canvas-api/add
|
|
||||||
Content-Type: application/json
|
|
||||||
|
|
||||||
{
|
The backend API is documented using Swagger/OpenAPI. After starting the backend service, you can access the API documentation at:
|
||||||
"student_id": 123,
|
- Development: http://localhost:14000/api-docs
|
||||||
"course_id": 456,
|
- Production: http://your-domain/api-docs
|
||||||
"assignment_id": 789,
|
|
||||||
"score": 85
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Response:
|
## Troubleshooting
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "Dummy grade added successfully",
|
|
||||||
"data": {
|
|
||||||
"id": 3,
|
|
||||||
"student_id": 123,
|
|
||||||
"course_id": 456,
|
|
||||||
"assignment_id": 789,
|
|
||||||
"score": 85,
|
|
||||||
"grade": "B",
|
|
||||||
"submitted_at": "2024-03-15T10:00:00Z",
|
|
||||||
"graded_at": "2024-03-16T14:30:00Z"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Update a Dummy Grade
|
1. **Port Conflicts**
|
||||||
```bash
|
- If you encounter port conflicts, check which services are running:
|
||||||
PUT /api/v1/canvas-api/update
|
```bash
|
||||||
Content-Type: application/json
|
docker ps
|
||||||
|
```
|
||||||
|
- Or check for processes using the ports:
|
||||||
|
```bash
|
||||||
|
lsof -i :3000
|
||||||
|
lsof -i :14000
|
||||||
|
```
|
||||||
|
|
||||||
{
|
2. **Database Issues**
|
||||||
"id": 1,
|
- Ensure PostgreSQL is running and accessible
|
||||||
"student_id": 123,
|
- Check database connection settings in `.env`
|
||||||
"course_id": 456,
|
- Verify database migrations are up to date
|
||||||
"assignment_id": 789,
|
|
||||||
"score": 90
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Response:
|
3. **CORS Issues**
|
||||||
```json
|
- If you see CORS errors, verify the frontend's API base URL
|
||||||
{
|
- Check backend CORS configuration
|
||||||
"success": true,
|
- Ensure both services are running on the correct ports
|
||||||
"message": "Dummy grade updated successfully",
|
|
||||||
"data": {
|
|
||||||
"id": 1,
|
|
||||||
"student_id": 123,
|
|
||||||
"course_id": 456,
|
|
||||||
"assignment_id": 789,
|
|
||||||
"score": 90,
|
|
||||||
"grade": "A",
|
|
||||||
"submitted_at": "2024-03-15T10:00:00Z",
|
|
||||||
"graded_at": "2024-03-16T14:30:00Z"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Delete a Dummy Grade
|
## Contributing
|
||||||
```bash
|
|
||||||
DELETE /api/v1/canvas-api/delete
|
|
||||||
Content-Type: application/json
|
|
||||||
|
|
||||||
{
|
1. Create a new branch for your feature
|
||||||
"id": 1
|
2. Make your changes
|
||||||
}
|
3. Submit a pull request
|
||||||
```
|
4. Ensure all tests pass
|
||||||
|
5. Update documentation as needed
|
||||||
|
|
||||||
Response:
|
## License
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "Dummy grade deleted successfully"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||||
|
|
||||||
## 10. Testing
|
|
||||||
|
|
||||||
Run tests with:
|
|
||||||
```bash
|
|
||||||
npm test # Run all tests
|
|
||||||
npm run test:watch # Run tests in watch mode
|
|
||||||
npm run test:coverage # Run tests with coverage
|
|
||||||
```
|
|
||||||
|
|
||||||
The test database is automatically used for running tests.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 11. Authentication & Authorization
|
|
||||||
|
|
||||||
- All endpoints except login require a valid JWT token
|
|
||||||
- The JWT token should be included in the Authorization header as: `Bearer your.jwt.token`
|
|
||||||
- Some endpoints require specific roles (admin/user)
|
|
||||||
- JWT tokens expire after 1 hour
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 12. Troubleshooting
|
|
||||||
|
|
||||||
### Common Issues
|
|
||||||
|
|
||||||
1. **Database Connection Issues**
|
|
||||||
- Ensure Docker is running
|
|
||||||
- Check if the Postgres containers are up: `docker ps`
|
|
||||||
- Verify database credentials in `.env`
|
|
||||||
|
|
||||||
2. **Authentication Issues**
|
|
||||||
- Ensure JWT_SECRET is set in `.env`
|
|
||||||
- Check if the user exists in the database
|
|
||||||
- Verify the password is correct
|
|
||||||
|
|
||||||
3. **Role-based Access Issues**
|
|
||||||
- Ensure the user has the required role
|
|
||||||
- Check if the JWT token includes the correct roles
|
|
||||||
- Verify the token hasn't expired
|
|
||||||
|
|
||||||
### Logs
|
|
||||||
|
|
||||||
- Application logs can be viewed in the terminal where `npm run dev` was executed
|
|
||||||
- Database logs can be viewed using: `docker logs fusero-boilerplate-db`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 13. Notes
|
|
||||||
|
|
||||||
- The app uses separate databases, ports, and Docker volumes from any other Fusero projects, so it can run in parallel.
|
|
||||||
- The default admin user is created by the seed script and can be changed via `.env`.
|
|
||||||
- For production, use `docker-compose.yml` and adjust ports/credentials as needed.
|
|
||||||
- The app includes TypeScript, ESLint, and Prettier for code quality.
|
|
||||||
|
|
||||||
---
|
|
||||||
Loading…
Reference in New Issue
Block a user