From 5e201cc033d10ea841ddd5965a47f92cff4e8abe Mon Sep 17 00:00:00 2001 From: DarrenT~ Date: Wed, 30 Apr 2025 17:38:24 +0200 Subject: [PATCH] add readme for running frontend --- README.md | 412 ++++++++++++++---------------------------------------- 1 file changed, 105 insertions(+), 307 deletions(-) diff --git a/README.md b/README.md index 2ef0928..c6536bc 100644 --- a/README.md +++ b/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. -It is set up to run alongside other projects without port or database conflicts. +A full-stack application boilerplate with React frontend and Node.js backend. ---- +## Project Structure -## 1. Prerequisites - -- [Node.js](https://nodejs.org/) (v18+ recommended) -- [Docker](https://www.docker.com/get-started) -- [npm](https://www.npmjs.com/) - ---- - -## 2. Clone the Repo - -```bash -git clone -cd fusero-app-boilerplate +``` +fusero-app-boilerplate/ +├── frontend/ # React frontend application +├── backend/ # Node.js backend application +├── docker-compose.yml # Production Docker configuration +└── docker-compose.dev.yml # Development Docker configuration ``` ---- +## 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 -# Database connection for Docker -POSTGRES_NAME=fusero-boilerplate-db -POSTGRES_HOSTNAME=localhost -POSTGRES_PORT=19095 -POSTGRES_USER=root -POSTGRES_PASSWORD=root123 +### Option 1: Running with Docker (Recommended for Development) -# Test Database connection -POSTGRES_TEST_NAME=test-db -POSTGRES_TEST_PORT=19096 +1. **Start the Development Environment** + ```bash + 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 -DEFAULT_ADMIN_USERNAME=darren -DEFAULT_ADMIN_EMAIL=darren@fusero.nl -DEFAULT_ADMIN_PASSWORD=admin123 +### Option 2: Running Services Separately (Recommended for Debugging) -# JWT secret -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 +For better debugging experience, you can run the frontend and backend in separate terminal windows: +#### Terminal 1: Backend Service ```bash +cd backend 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 ``` +The backend will be available at http://localhost:14000 -The app will be available at [http://localhost:14000](http://localhost:14000). - ---- - -## 9. API Endpoints - -### Authentication - -#### Login +#### Terminal 2: Frontend Service ```bash -curl -X POST http://localhost:14000/api/v1/auth/login \ --H "Content-Type: application/json" \ --d '{ - "username": "darren", - "password": "admin123" -}' +cd frontend +npm install +npm run dev ``` +The frontend will be available at http://localhost:3000 -Response: -```json -{ - "success": true, - "message": "Authentication successful", - "data": { - "token": "your.jwt.token", - "user": { - "id": 1, - "username": "darren", - "email": "darren@fusero.nl", - "roles": ["admin"] - } - } -} -``` +### Environment Setup -### 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 -```bash -curl -X POST http://localhost:14000/api/v1/app/users \ --H "Content-Type: application/json" \ --H "Authorization: Bearer your.jwt.token" \ --d '{ - "username": "newuser", - "password": "userpass123", - "email": "user@example.com", - "roleName": "user" -}' -``` +2. **Frontend Environment** + - Copy `.env.example` to `.env` in the frontend directory + - Set the API base URL: + ``` + VITE_API_BASE_URL=http://localhost:14000/api/v1 + ``` -Response: -```json -{ - "success": true, - "message": "User created successfully", - "data": { - "id": 2, - "username": "newuser", - "email": "user@example.com", - "roles": ["user"] - } -} -``` +## Production Deployment -#### Get All Users (Requires admin role) -```bash -curl -X GET http://localhost:14000/api/v1/app/users \ --H "Authorization: Bearer your.jwt.token" -``` +1. **Build and Run with Docker** + ```bash + docker-compose up --build + ``` -#### Get User by ID -```bash -curl -X GET http://localhost:14000/api/v1/app/users/1 \ --H "Authorization: Bearer your.jwt.token" -``` +2. **Environment Variables** + - Ensure all environment variables are properly set in your production environment + - Never commit `.env` files to version control -### 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 -```bash -GET /api/v1/canvas-api/ -``` +2. **Code Organization** + - Frontend code should be in the `frontend/` directory + - Backend code should be in the `backend/` directory + - Shared types and utilities should be in their respective directories -Response: -```json -{ - "success": true, - "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" - } - ] - } -} -``` +3. **Version Control** + - Commit `package-lock.json` files + - Don't commit `.env` files + - Use meaningful commit messages -#### Add a New Dummy Grade -```bash -POST /api/v1/canvas-api/add -Content-Type: application/json +## API Documentation -{ - "student_id": 123, - "course_id": 456, - "assignment_id": 789, - "score": 85 -} -``` +The backend API is documented using Swagger/OpenAPI. After starting the backend service, you can access the API documentation at: +- Development: http://localhost:14000/api-docs +- Production: http://your-domain/api-docs -Response: -```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" - } -} -``` +## Troubleshooting -#### Update a Dummy Grade -```bash -PUT /api/v1/canvas-api/update -Content-Type: application/json +1. **Port Conflicts** + - If you encounter port conflicts, check which services are running: + ```bash + docker ps + ``` + - Or check for processes using the ports: + ```bash + lsof -i :3000 + lsof -i :14000 + ``` -{ - "id": 1, - "student_id": 123, - "course_id": 456, - "assignment_id": 789, - "score": 90 -} -``` +2. **Database Issues** + - Ensure PostgreSQL is running and accessible + - Check database connection settings in `.env` + - Verify database migrations are up to date -Response: -```json -{ - "success": true, - "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" - } -} -``` +3. **CORS Issues** + - If you see CORS errors, verify the frontend's API base URL + - Check backend CORS configuration + - Ensure both services are running on the correct ports -#### Delete a Dummy Grade -```bash -DELETE /api/v1/canvas-api/delete -Content-Type: application/json +## Contributing -{ - "id": 1 -} -``` +1. Create a new branch for your feature +2. Make your changes +3. Submit a pull request +4. Ensure all tests pass +5. Update documentation as needed -Response: -```json -{ - "success": true, - "message": "Dummy grade deleted successfully" -} -``` +## License ---- - -## 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. - ---- \ No newline at end of file +This project is licensed under the MIT License - see the LICENSE file for details. \ No newline at end of file