diff --git a/README.md b/README.md index 46bfc59..4cb660b 100644 --- a/README.md +++ b/README.md @@ -130,297 +130,17 @@ fusero-app-boilerplate/ ## โš™๏ธ Prerequisites -- Node.js (v20 or higher) -- npm (v9 or higher) -- Docker & Docker Compose +- Node.js (v20 or higher) +- npm (v9 or higher) +- Docker and Docker Compose - Git ---- +## Development Setup -## ๐Ÿ’ป 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. -๐Ÿ—ƒ๏ธ PostgreSQL must run in Docker for consistent behavior. - -Create volume and start the database: -docker volume create fusero-dev-db-data -docker-compose up -d db - -Backend setup: -cd backend -cp .env.example .env -npm install -# To create a new migration: -# npm run migration:create -# To apply migrations: -npm run migrate -# To seed the database: -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 - ---- - -## ๐Ÿณ Docker Development - -๐Ÿ—ƒ๏ธ PostgreSQL must run in Docker for consistent behavior. - -Create volume and start the database: -docker volume create fusero-dev-db-data -docker-compose up -d db - -Backend setup: -cd backend -cp .env.example .env -npm install -# To create a new migration: -# npm run migration:create -# To apply migrations: -npm run migrate -# To seed the database: -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 - ---- - -## ๐Ÿš€ Kubernetes 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 npm run migrate -docker exec -it fusero-app-backend npm run seed - -3. Ensure all required environment variables are configured. - ---- - -## ๐ŸŒ 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.yaml` 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.yaml` 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.yaml down -docker-compose -f docker-compose.dev.yaml 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 -```bash -docker push /fusero-backend-dev:local -``` - -### 3. Upgrade the Helm release with the latest values -```bash -helm upgrade fusero ./chart -n fusero -f chart/values.dev.yaml -``` - -### 4. Restart the backend deployment to pick up new images and env vars -```bash -kubectl rollout restart deployment/fusero-backend -n fusero -``` - -### 5. Check backend pod environment variables -```bash -kubectl get pods -n fusero -# Replace with the actual pod name from above -kubectl exec -n fusero -- printenv | grep POSTGRES -``` - -### 6. Check backend pod logs for errors -```bash -kubectl logs -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 +To start the database: ```bash docker build -t fusero-frontend-dev:local ./frontend ``` diff --git a/chart/values.dev.yaml b/chart/values.dev.yaml new file mode 100644 index 0000000..17cef7d --- /dev/null +++ b/chart/values.dev.yaml @@ -0,0 +1,34 @@ +global: + imagePullPolicy: IfNotPresent + +backend: + image: fusero-backend-dev:local + port: 14000 + env: + CORS_ORIGIN: "*" + POSTGRES_NAME: fusero-boilerplate-db + POSTGRES_HOSTNAME: postgres-service + POSTGRES_USER: root + POSTGRES_PASSWORD: root123 + POSTGRES_PORT: "5432" + DEFAULT_ADMIN_USERNAME: admin + DEFAULT_ADMIN_EMAIL: darren@fusero.nl + DEFAULT_ADMIN_PASSWORD: admin123 + ENCRYPTION_KEY: d3680f1c027e865e1da5c2be8b0be20c43f70a8107071e61df15cab6df4357cf + JWT_SECRET: sdfj94mfm430f72m3487rdsjiy7834n9rnf934n8r3n490fn4u83fh894hr9nf0 + CHATGPT_API_KEY: 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 + CANVAS_API_KEY: 17601~vLkPEraKTtCmxrNx48TH9JW8ePtUPG2tHLZu8mauAuUeyXePXKY67axYaWRrN43x + CANVAS_API_URL: https://talnet.instructure.com/api/v1 + +frontend: + image: fusero-frontend-dev:devserver + port: 8080 + env: + VITE_API_BASE_URL: http://localhost:14000 + +postgres: + image: postgres:15 + storage: 1Gi + dbName: fusero-boilerplate-db + user: root + password: root123 diff --git a/chart/values.prod.yml b/chart/values.prod.yml new file mode 100644 index 0000000..321ca39 --- /dev/null +++ b/chart/values.prod.yml @@ -0,0 +1,22 @@ +backend: + image: fusero-backend:latest + env: + POSTGRES_HOST: postgres-service + POSTGRES_PORT: "5432" + POSTGRES_NAME: fusero-db + POSTGRES_USER: prod_admin + POSTGRES_PASSWORD: REPLACE_ME + DEFAULT_ADMIN_USERNAME: admin + DEFAULT_ADMIN_EMAIL: admin@fusero.nl + DEFAULT_ADMIN_PASSWORD: STRONG_REPLACE_ME + ENCRYPTION_KEY: PROD_REPLACE_ME_KEY + JWT_SECRET: PROD_REPLACE_ME_JWT + CHATGPT_API_KEY: PROD_REPLACE_ME_CHATGPT + CANVAS_API_KEY: PROD_REPLACE_ME_CANVAS + +frontend: + image: fusero-frontend:latest + +postgres: + image: postgres:15 + storage: 5Gi