⚡️ 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

• ⚡️ Fusero App Boilerplate
  • 📚 Table of Contents
  • 📁 Project Structure
  • ⚙️ Prerequisites
  • Development Setup
    • Important Note: Database Must Run in Docker
    • Running Services Separately (Recommended for Development)
      • Terminal 1: Backend Service
    • 2. (If using a remote registry) Push the image
    • 3. Upgrade the Helm release with the latest values
    • 4. Restart the backend deployment to pick up new images and env vars
    • 5. Check backend pod environment variables
    • 6. Check backend pod logs for errors
    • 7. If you change DB env vars or code, repeat steps 1-6
  • Frontend Rebuild & Redeploy (Kubernetes)
    • 1. Rebuild the frontend Docker image
    • 2. (If using a remote registry) Push the image
    • 3. Upgrade the Helm release
    • 4. Restart the frontend deployment
  • Port-Forwarding for Local Access
    • Frontend (React app)
    • Backend (API)
  • NGINX Backend Service Name: Docker Compose vs Kubernetes
    • How to update the NGINX config for Kubernetes
  • Cleaning Up Duplicate or Crashing Deployments and Pods in Kubernetes
    • 1. List deployments and pods
    • 2. Delete old or crashing deployments (example IDs from your cluster)
    • 3. Delete old or crashing pods (example IDs from your cluster)
  • Debugging Frontend Pod Crashes: NGINX SSL Certificate Errors
    • How to fix for Kubernetes (Recommended)
  • Connecting to the Database from Your Host (DBeaver, etc.)

---

📁 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 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 up db

Running Services Separately (Recommended for Development)

For better debugging experience, 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 up db
   

2. Then, in separate terminal windows:

Terminal 1: Backend Service

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)
```bash
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

• Access at: http://localhost:3000

Backend (API)

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

• Access at: http://localhost: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.

---