force push readme
This commit is contained in:
commit
3035a313a2
294
README.md
294
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 <your-registry>/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 <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
|
||||
```bash
|
||||
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
|
||||
To start the database:
|
||||
```bash
|
||||
docker build -t fusero-frontend-dev:local ./frontend
|
||||
```
|
||||
|
||||
34
chart/values.dev.yaml
Normal file
34
chart/values.dev.yaml
Normal file
@ -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
|
||||
22
chart/values.prod.yml
Normal file
22
chart/values.prod.yml
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user