144 lines
3.7 KiB
Markdown
144 lines
3.7 KiB
Markdown
# 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
|
|
|
|
### Option 1: Running with Docker (Recommended for Development)
|
|
|
|
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
|
|
|
|
### Option 2: Running Services Separately (Recommended for Debugging)
|
|
|
|
For better debugging experience, you can run the frontend and backend in separate terminal windows:
|
|
|
|
#### Terminal 1: Backend Service
|
|
```bash
|
|
cd backend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
The backend will be available at http://localhost:14000
|
|
|
|
#### Terminal 2: Frontend Service
|
|
```bash
|
|
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**
|
|
```bash
|
|
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. **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
|
|
|
|
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
|
|
|
|
3. **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:
|
|
```bash
|
|
docker ps
|
|
```
|
|
- Or check for processes using the ports:
|
|
```bash
|
|
lsof -i :3000
|
|
lsof -i :14000
|
|
```
|
|
|
|
2. **Database Issues**
|
|
- Ensure PostgreSQL is running and accessible
|
|
- Check database connection settings in `.env`
|
|
- Verify database migrations are up to date
|
|
|
|
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. |