fusero-group/fusero-app-boilerplate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ce4371d9e4
fusero-app-boilerplate/README.md

15 KiB
Raw Blame History

⚡️ Fusero App Boilerplate

A full-stack application boilerplate with a React frontend and Node.js backend — powered by Fastify, Vite, PostgreSQL, Docker, and optional Kubernetes & Helm support. Built for modern dev workflows and AI-powered backend endpoint generation.

📚 Table of Contents

📁 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
└── chart/ # Helm chart for Kubernetes deployment

⚙️ Prerequisites

  • Node.js (v20 or higher)
  • npm (v9 or higher)
  • Docker & Docker Compose
  • Git

💻 Development Setup

🗃️ PostgreSQL must run in Docker for consistent behavior.

Create volume and start the database:
docker volume create fusero-db-data
docker-compose up -d db

Backend setup:
cd backend
cp .env.example .env
npm install
npm run migrate
npm run seed
npm run dev &
cd ..

Frontend setup:
cd frontend
cp .env.example .env
npm install
npm run dev &
cd ..

App is running:
Frontend → http://localhost:3000
Backend → http://localhost:14000

Alternate: Running Services in Separate Terminals

Terminal 1 (backend):
cd backend
npm install
npm run dev

Terminal 2 (frontend):
cd frontend
npm install
npm run dev

🛠️ Environment Setup

backend/.env:
POSTGRES_NAME=fusero-boilerplate-db
POSTGRES_HOSTNAME=localhost
POSTGRES_PORT=19095
POSTGRES_USER=root
POSTGRES_PASSWORD=root123
JWT_SECRET=your_jwt_secret_key_here

For Kubernetes, these are set in chart/values.yaml:

POSTGRES_NAME=fusero-boilerplate-db

POSTGRES_HOSTNAME=postgres-service

POSTGRES_PORT=19095

POSTGRES_USER=root

POSTGRES_PASSWORD=root123

frontend/.env:
VITE_API_BASE_URL=http://localhost:14000/api/v1

🚀 Production Deployment

  1. Build and run with Docker:
    docker-compose up --build

  2. Apply migrations and seed inside backend container:
    docker exec -it fusero-app-backend npx mikro-orm migration:up
    docker exec -it fusero-app-backend npm run seed

  3. Ensure all required environment variables are configured.
    Never commit .env files.

🌐 Frontend Routing in Production

In production, the frontend is served through NGINX.

NGINX configuration (important for React routing):
location / {
 try_files $uri $uri/ /index.html;
}

React Router Configuration:
Use basename="/" in dev, and basename="/dashboard" in production.

Use relative paths in links:
Correct: to="canvas/canvas-endpoints"
Wrong: to="/dashboard/canvas/canvas-endpoints"

🔐 HTTPS with Self-Signed Certificates

Generate a self-signed cert:
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./nginx/ssl/nginx.key -out ./nginx/ssl/nginx.crt

Ensure docker-compose.yml mounts the certs:
volumes:

  • ./nginx/ssl:/etc/nginx/ssl

Configure NGINX to use the cert in production.

🧠 Development Best Practices

  • Always run the DB via Docker
  • Use docker-compose.dev.yml for development
  • Never run PostgreSQL directly on host
  • Run frontend and backend separately for hot reload
  • Use .env.example as a template
  • Never commit .env
  • Commit package-lock.json
  • Use meaningful commit messages

📘 API Documentation

After running the backend:

Development → http://localhost:14000/api-docs
Production → https://your-domain/api-docs

🧩 ChatGPT-Powered Endpoint Creation

Prompts like "Create a course endpoint for Canvas" auto-generate API endpoints.

How it works:

  1. The frontend sends your prompt to /api/v1/canvas-api/chatgpt/completions
  2. If ChatGPT returns a valid endpoint JSON, it's POSTed to /api/v1/canvas-api/endpoints
  3. The UI auto-refreshes the endpoint list and shows a toast

Example Prompt:
Create a course endpoint for Canvas.

Expected JSON:
{
 "name": "Create Course",
 "method": "POST",
 "path": "/courses",
 "description": "Creates a new course in Canvas."
}

Developer Notes:

  • Frontend logic: frontend/src/components/CanvasEndpoints.tsx
  • Backend API: /api/v1/canvas-api/endpoints

🧪 Troubleshooting

Port Conflicts:
docker ps
lsof -i :3000
lsof -i :14000

Database Issues:
Ensure DB is in Docker and configured correctly
Try restarting:
docker-compose -f docker-compose.dev.yml down
docker-compose -f docker-compose.dev.yml up db

CORS Issues:
Check API base URL in frontend .env
Check backend CORS settings
Verify ports match and services are running

🤝 Contributing

  1. Create a branch
  2. Make your changes
  3. Pass all tests
  4. Open a pull request
  5. Update docs if needed

📄 License

This project is licensed under the MIT License.
See the LICENSE file for full details.

Kubernetes Troubleshooting & Redeployment Commands

If your backend is not picking up environment variables or is failing to connect to the database, follow these steps:

1. Rebuild the backend Docker image (after code/config changes)

docker build -t fusero-backend-dev:local .

2. (If using a remote registry) Push the image

docker push <your-registry>/fusero-backend-dev:local

3. Upgrade the Helm release with the latest values

helm upgrade fusero ./chart -n fusero -f chart/values.dev.yaml

4. Restart the backend deployment to pick up new images and env vars

kubectl rollout restart deployment/fusero-backend -n fusero

5. Check backend pod environment variables

kubectl get pods -n fusero
# Replace <backend-pod-name> with the actual pod name from above
kubectl exec -n fusero <backend-pod-name> -- printenv | grep POSTGRES

6. Check backend pod logs for errors

kubectl logs <backend-pod-name> -n fusero --tail=50

7. If you change DB env vars or code, repeat steps 1-6

Note:

  • Make sure your backend code does NOT load .env at runtime in Kubernetes. It should use the environment variables provided by the pod.
  • If you see connection errors to the DB, always check the pod's environment and logs as above.

Frontend Rebuild & Redeploy (Kubernetes)

If you change the VITE_API_BASE_URL or any frontend environment variable, rebuild and redeploy the frontend:

1. Rebuild the frontend Docker image

docker build -t fusero-frontend-dev:local ./frontend

2. (If using a remote registry) Push the image

docker push <your-registry>/fusero-frontend-dev:local

3. Upgrade the Helm release

helm upgrade fusero ./chart -n fusero -f chart/values.dev.yaml

4. Restart the frontend deployment

kubectl rollout restart deployment/fusero-frontend -n fusero

Port-Forwarding for Local Access

To access your services running in Kubernetes from your local machine, use these commands:

Frontend (React app)

kubectl port-forward -n fusero svc/fusero-frontend-service 3000:80

Backend (API)

kubectl port-forward -n fusero svc/fusero-backend-service 14000:14000

NGINX Backend Service Name: Docker Compose vs Kubernetes

If your frontend uses NGINX to proxy API requests, you must update the backend service name depending on your environment:

  • Docker Compose/local: The backend may be named fusero-app-backend.
  • Kubernetes: The backend service is named fusero-backend-service.

How to update the NGINX config for Kubernetes

Edit frontend/nginx.conf:

Change this:

proxy_pass http://fusero-app-backend:14000/;

To this:

proxy_pass http://fusero-backend-service:14000/;

Then rebuild and redeploy the frontend:

docker build -t fusero-frontend-dev:local ./frontend
# (push if needed)
helm upgrade fusero ./chart -n fusero -f chart/values.dev.yaml
kubectl rollout restart deployment/fusero-frontend -n fusero

If you see an NGINX error like host not found in upstream, this is the cause!

Cleaning Up Duplicate or Crashing Deployments and Pods in Kubernetes

If you see multiple frontend or backend pods (or CrashLoopBackOff errors), clean up your namespace with these steps:

1. List deployments and pods

kubectl get deployments -n fusero
kubectl get pods -n fusero

2. Delete old or crashing deployments (example IDs from your cluster)

kubectl delete deployment fusero-frontend-65cb8db99d -n fusero
kubectl delete deployment fusero-frontend-74fcbb778 -n fusero

3. Delete old or crashing pods (example IDs from your cluster)

kubectl delete pod fusero-frontend-65cb8db99d-f2lhr -n fusero
kubectl delete pod fusero-frontend-74fcbb778-v89gm -n fusero

Tip: Only keep the latest, healthy pods and deployments. If in doubt, check with kubectl get deployments -n fusero and kubectl get pods -n fusero before deleting.

Debugging Frontend Pod Crashes: NGINX SSL Certificate Errors

If your frontend pod crashes with an error like:

nginx: [emerg] cannot load certificate "/etc/nginx/certs/fusero-selfsigned.crt": BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory)

This means NGINX is trying to load an SSL certificate that does not exist in the pod.

How to fix for Kubernetes (Recommended)

  1. Edit frontend/nginx.conf:
    • Change: 
      listen 14443 ssl;
ssl_certificate /etc/nginx/certs/fusero-selfsigned.crt;
ssl_certificate_key /etc/nginx/certs/fusero-selfsigned.key;
    • To: 
      listen 8080;
# (remove the ssl_certificate and ssl_certificate_key lines)
  2. Rebuild the frontend Docker image: 
    docker build --no-cache -t fusero-frontend-dev:local ./frontend
  3. (If using a remote registry) Push the image.
  4. Redeploy with Helm: 
    helm upgrade fusero ./chart -n fusero -f chart/values.dev.yaml
  5. Check pod status: 
    kubectl get pods -n fusero

This will make NGINX listen on port 8080 without SSL, which is standard for in-cluster Kubernetes services.

Connecting to the Database from Your Host (DBeaver, etc.)

To connect to the Postgres database running in Kubernetes from your local machine (for example, using DBeaver or another SQL client):

  1. Port-forward the Postgres service:

    kubectl port-forward svc/postgres-service 5432:5432
    • Keep this terminal open while you use your database client.
    • If port 5432 is in use on your machine, you can use another local port (e.g., 15432:5432) and connect to port 15432 in your client.

  2. Database connection settings:

    • Host: localhost
    • Port: 5432 (or your chosen local port)
    • Database: fusero-boilerplate-db
    • Username: root
    • Password: root123

  3. Open DBeaver (or your preferred client) and create a new Postgres connection using the above settings.

  4. Test the connection.