fusero-app-boilerplate/README.md

Fusero App Boilerplate

A full-stack application boilerplate with React frontend and Node.js backend.

Project Structure

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

• Node.js (v18 or higher)
• npm (v9 or higher)
• Docker and Docker Compose
• Git

Development Setup

Important Note: Database Must Run in Docker

The PostgreSQL database must always run in Docker, regardless of your development setup choice. This ensures consistent database behavior across all environments.

To start the database:

docker-compose -f docker-compose.dev.yml up db

Option 1: Running Everything in Docker (Recommended for Development)

1. Start the Development Environment

   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

Option 2: Running Services Separately (Recommended for Debugging)

For better debugging experience, you can run the frontend and backend in separate terminal windows, while keeping the database in Docker:

1. First, ensure the database is running in Docker

   docker-compose -f docker-compose.dev.yml up db
   

2. Then, in separate terminal windows:

Terminal 1: Backend Service

cd backend
npm install
npm run dev

The backend will be available at http://localhost:14000

Terminal 2: Frontend Service

cd frontend
npm install
npm run dev

The frontend will be available at http://localhost:3000

Environment Setup

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
     

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
     

Production Deployment

1. Build and Run with Docker

   docker-compose up --build
   

2. Environment Variables

   • Ensure all environment variables are properly set in your production environment
   • Never commit .env files to version control

Development Best Practices

1. Database Management

   • Always run the database in Docker
   • Use docker-compose.dev.yml for development
   • Never run PostgreSQL directly on your host machine

2. 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

3. 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

4. Version Control

   • Commit package-lock.json files
   • Don't commit .env files
   • Use meaningful commit messages

API Documentation

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

Troubleshooting

1. Port Conflicts

   • If you encounter port conflicts, check which services are running:

     docker ps
     

   • Or check for processes using the ports:

     lsof -i :3000
     lsof -i :14000
     

2. Database Issues

   • Ensure PostgreSQL is running in Docker
   • Check database connection settings in .env
   • Verify database migrations are up to date
   • If database issues persist, try:

     docker-compose -f docker-compose.dev.yml down
     docker-compose -f docker-compose.dev.yml up db
     

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

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.