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.
|
||||
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 <your-repo-url>
|
||||
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.
|
||||
|
||||
---
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
Loading…
Reference in New Issue
Block a user