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

Merge branch 'main' into k8s-deployment

Browse Source
This commit is contained in:
liquidrinu 2025-05-21 02:12:52 +02:00
commit 797fc34016
4 changed files with 305 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
README.md
View File

@ -10,26 +10,10 @@ A full-stack application boilerplate with a React frontend and Node.js backend
- [📚 Table of Contents](#-table-of-contents) - [📚 Table of Contents](#-table-of-contents)
- [📁 Project Structure](#-project-structure) - [📁 Project Structure](#-project-structure)
- [⚙️ Prerequisites](#️-prerequisites) - [⚙️ Prerequisites](#️-prerequisites)
- [💻 Development Setup](#-development-setup) - [Development Setup](#development-setup)
- [Alternate: Running Services in Separate Terminals](#alternate-running-services-in-separate-terminals) - [Important Note: Database Must Run in Docker](#important-note-database-must-run-in-docker)
- [🛠️ Environment Setup](#️-environment-setup) - [Running Services Separately (Recommended for Development)](#running-services-separately-recommended-for-development)
- [For Kubernetes, these are set in chart/values.yaml:](#for-kubernetes-these-are-set-in-chartvaluesyaml) - [Terminal 1: Backend Service](#terminal-1-backend-service)
- [POSTGRES\_NAME=fusero-boilerplate-db](#postgres_namefusero-boilerplate-db)
- [POSTGRES\_HOSTNAME=postgres-service](#postgres_hostnamepostgres-service)
- [POSTGRES\_PORT=19095](#postgres_port19095)
- [POSTGRES\_USER=root](#postgres_userroot)
- [POSTGRES\_PASSWORD=root123](#postgres_passwordroot123)
- [🚀 Production Deployment](#-production-deployment)
- [🌐 Frontend Routing in Production](#-frontend-routing-in-production)
- [🔐 HTTPS with Self-Signed Certificates](#-https-with-self-signed-certificates)
- [🧠 Development Best Practices](#-development-best-practices)
- [📘 API Documentation](#-api-documentation)
- [🧩 ChatGPT-Powered Endpoint Creation](#-chatgpt-powered-endpoint-creation)
- [🧪 Troubleshooting](#-troubleshooting)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
- [Kubernetes Troubleshooting \& Redeployment Commands](#kubernetes-troubleshooting--redeployment-commands)
- [1. Rebuild the backend Docker image (after code/config changes)](#1-rebuild-the-backend-docker-image-after-codeconfig-changes)
- [2. (If using a remote registry) Push the image](#2-if-using-a-remote-registry-push-the-image) - [2. (If using a remote registry) Push the image](#2-if-using-a-remote-registry-push-the-image)
- [3. Upgrade the Helm release with the latest values](#3-upgrade-the-helm-release-with-the-latest-values) - [3. Upgrade the Helm release with the latest values](#3-upgrade-the-helm-release-with-the-latest-values)
- [4. Restart the backend deployment to pick up new images and env vars](#4-restart-the-backend-deployment-to-pick-up-new-images-and-env-vars) - [4. Restart the backend deployment to pick up new images and env vars](#4-restart-the-backend-deployment-to-pick-up-new-images-and-env-vars)
@ -69,48 +53,36 @@ fusero-app-boilerplate/
## ⚙️ Prerequisites ## ⚙️ Prerequisites
- Node.js (v20 or higher) - Node.js (v20 or higher)
- npm (v9 or higher) - npm (v9 or higher)
- Docker & Docker Compose - Docker and Docker Compose
- Git - 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. To start the database:
```bash
docker-compose up db
```
Create volume and start the database: ### Running Services Separately (Recommended for Development)
docker volume create fusero-db-data
docker-compose up -d db
Backend setup: For better debugging experience, run the frontend and backend in separate terminal windows, while keeping the database in Docker:
cd backend
cp .env.example .env
npm install
npm run migrate
npm run seed
npm run dev &
cd ..
Frontend setup: 1. **First, ensure the database is running in Docker**
cd frontend ```bash
cp .env.example .env docker-compose up db
npm install ```
npm run dev &
cd ..
App is running: 2. **Then, in separate terminal windows:**
Frontend → http://localhost:3000
Backend → http://localhost:14000
--- #### Terminal 1: Backend Service
```bash
### Alternate: Running Services in Separate Terminals cd backend
npm install
Terminal 1 (backend):
cd backend
npm install
npm run dev npm run dev
Terminal 2 (frontend): Terminal 2 (frontend):

22
chart/values.prod.yml Normal file
View 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

130
docs/DEPLOY.md Normal file
View File

@ -0,0 +1,130 @@
# 📦 Fusero VPS Deployment Guide
This guide walks you through deploying the Fusero full-stack app to a plain Ubuntu VPS using Kubernetes (k3s), Helm, and automatic HTTPS via cert-manager.
---
## 📋 Prerequisites
- ✅ Ubuntu 22.04 VPS with root or sudo access
- ✅ Domain names pointed to your VPS IP:
- api.fusero.nl → for the backend
- app.fusero.nl → for the frontend
- ✅ Git access to your repo
---
## ☸️ 1. Install Kubernetes (k3s)
curl -sfL https://get.k3s.io | sh -
Set kubeconfig so kubectl works:
echo 'export KUBECONFIG=/etc/rancher/k3s/k3s.yaml' >> ~/.bashrc
source ~/.bashrc
Verify:
kubectl get nodes
---
## 📦 2. Install Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
Verify:
helm version
---
## 📁 3. Clone the Project
git clone https://your.gitea.repo/fusero-app-boilerplate.git
cd fusero-app-boilerplate
---
## 🔐 4. Set Up HTTPS (cert-manager)
Install cert-manager:
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
Check pods:
kubectl get pods -n cert-manager
Create file cluster-issuer.yaml with this content:
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: your@email.com
privateKeySecretRef:
name: letsencrypt-prod
solvers:
- http01:
ingress:
class: nginx
Apply it:
kubectl apply -f cluster-issuer.yaml
---
## 🌍 5. Update DNS
Ensure both api.fusero.nl and app.fusero.nl point to your VPS IP address.
Check propagation:
ping api.fusero.nl
---
## 🚀 6. Deploy with Helm
Ensure you're in the repo root and the chart directory exists.
helm upgrade --install fusero ./chart -f chart/values-prod.yaml
This deploys frontend, backend, Postgres, ingress, and HTTPS.
---
## 📜 7. Verify Access
Frontend: https://app.fusero.nl
Backend API: https://api.fusero.nl
---
## 🔁 8. (Optional) Rerun DB Migrations
kubectl delete job fusero-backend-db-init
helm upgrade fusero ./chart -f chart/values-prod.yaml
---
## 🧪 9. Useful Commands
View backend logs:
kubectl logs deployment/fusero-backend
View frontend logs:
kubectl logs deployment/fusero-frontend
View pods and services:
kubectl get pods,svc,deployments
---
## ✅ You’re Done!
You now have a production deployment of Fusero on a raw VPS with:
- Kubernetes (via k3s)
- TLS via Let's Encrypt
- Helm-managed services
- DNS routing for subdomains
For CI/CD automation via Gitea, see `.gitea-ci.yml` in the repo root.

128
docs/GUIDE-TO-K8S.md Normal file
View File

@ -0,0 +1,128 @@
# 📘 How to Install Kubernetes on Ubuntu 24.04 (Step-by-Step Guide)
This guide walks you through installing a multi-node Kubernetes cluster on Ubuntu 24.04 using `kubeadm`.
---
## 🧰 Prerequisites
* Ubuntu 24.04 instances with SSH enabled
* sudo user access
* At least 2GB RAM, 2 CPUs, and 20GB storage per node
* Internet access
### Sample Setup:
* **Master Node:** k8s-master-noble (192.168.1.120)
* **Worker 1:** k8s-worker01-noble (192.168.1.121)
* **Worker 2:** k8s-worker02-noble (192.168.1.122)
---
## 1️⃣ Set Hostnames & Update Hosts File
Run on each node:
sudo hostnamectl set-hostname "k8s-master-noble" # Master
sudo hostnamectl set-hostname "k8s-worker01-noble" # Worker 1
sudo hostnamectl set-hostname "k8s-worker02-noble" # Worker 2
Edit `/etc/hosts` on all nodes:
192.168.1.120 k8s-master-noble
192.168.1.121 k8s-worker01-noble
192.168.1.122 k8s-worker02-noble
---
## 2️⃣ Disable Swap & Load Kernel Modules
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab
sudo modprobe overlay
sudo modprobe br\_netfilter
echo -e "overlay\nbr\_netfilter" | sudo tee /etc/modules-load.d/k8s.conf
echo -e "net.bridge.bridge-nf-call-ip6tables = 1\nnet.bridge.bridge-nf-call-iptables = 1\nnet.ipv4.ip\_forward = 1" | sudo tee /etc/sysctl.d/kubernetes.conf
sudo sysctl --system
---
## 3️⃣ Install and Configure containerd
sudo apt install -y curl gnupg2 software-properties-common apt-transport-https ca-certificates
curl -fsSL [https://download.docker.com/linux/ubuntu/gpg](https://download.docker.com/linux/ubuntu/gpg) | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/containerd.gpg
sudo add-apt-repository "deb \[arch=amd64] [https://download.docker.com/linux/ubuntu](https://download.docker.com/linux/ubuntu) \$(lsb\_release -cs) stable"
sudo apt update && sudo apt install containerd.io -y
containerd config default | sudo tee /etc/containerd/config.toml > /dev/null
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
sudo systemctl restart containerd
---
## 4️⃣ Add Kubernetes Repository
curl -fsSL [https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key](https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key) | sudo gpg --dearmor -o /etc/apt/keyrings/k8s.gpg
echo "deb \[signed-by=/etc/apt/keyrings/k8s.gpg] [https://pkgs.k8s.io/core:/stable:/v1.30/deb/](https://pkgs.k8s.io/core:/stable:/v1.30/deb/) /" | sudo tee /etc/apt/sources.list.d/k8s.list
---
## 5️⃣ Install kubelet, kubeadm, kubectl
sudo apt update
sudo apt install kubelet kubeadm kubectl -y
---
## 6️⃣ Initialize Kubernetes Cluster (Master Node Only)
sudo kubeadm init --control-plane-endpoint=k8s-master-noble
Then set up kubectl:
mkdir -p \$HOME/.kube
sudo cp /etc/kubernetes/admin.conf \$HOME/.kube/config
sudo chown \$(id -u):\$(id -g) \$HOME/.kube/config
---
## 7️⃣ Join Worker Nodes
Use the join command from the `kubeadm init` output on each worker node:
sudo kubeadm join k8s-master-noble:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>
---
## 8️⃣ Install Calico Network Add-on (Master Only)
kubectl apply -f [https://raw.githubusercontent.com/projectcalico/calico/v3.29.1/manifests/calico.yaml](https://raw.githubusercontent.com/projectcalico/calico/v3.29.1/manifests/calico.yaml)
Check readiness:
kubectl get pods -n kube-system
kubectl get nodes
---
## 9️⃣ Test the Cluster
kubectl create ns demo-app
kubectl create deployment nginx-app --image nginx --replicas 2 --namespace demo-app
kubectl expose deployment nginx-app -n demo-app --type NodePort --port 80
kubectl get svc -n demo-app
Then access it:
curl http\://<worker-node-ip>:<node-port>
✅ You now have a fully functional Kubernetes cluster on Ubuntu 24.04!