diff --git a/README.md b/README.md index 3598aa6..62823d9 100644 --- a/README.md +++ b/README.md @@ -10,26 +10,10 @@ A full-stack application boilerplate with a React frontend and Node.js backend - [πŸ“š Table of Contents](#-table-of-contents) - [πŸ“ Project Structure](#-project-structure) - [βš™οΈ Prerequisites](#️-prerequisites) - - [πŸ’» Development Setup](#-development-setup) - - [Alternate: Running Services in Separate Terminals](#alternate-running-services-in-separate-terminals) - - [πŸ› οΈ Environment Setup](#️-environment-setup) -- [For Kubernetes, these are set in chart/values.yaml:](#for-kubernetes-these-are-set-in-chartvaluesyaml) -- [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) + - [Development Setup](#development-setup) + - [Important Note: Database Must Run in Docker](#important-note-database-must-run-in-docker) + - [Running Services Separately (Recommended for Development)](#running-services-separately-recommended-for-development) + - [Terminal 1: Backend Service](#terminal-1-backend-service) - [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) - [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 -- 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. +To start the database: +```bash +docker-compose up db +``` -Create volume and start the database: -docker volume create fusero-db-data -docker-compose up -d db +### Running Services Separately (Recommended for Development) -Backend setup: -cd backend -cp .env.example .env -npm install -npm run migrate -npm run seed -npm run dev & -cd .. +For better debugging experience, run the frontend and backend in separate terminal windows, while keeping the database in Docker: -Frontend setup: -cd frontend -cp .env.example .env -npm install -npm run dev & -cd .. +1. **First, ensure the database is running in Docker** + ```bash + docker-compose up db + ``` -App is running: -Frontend β†’ http://localhost:3000 -Backend β†’ http://localhost:14000 +2. **Then, in separate terminal windows:** ---- - -### Alternate: Running Services in Separate Terminals - -Terminal 1 (backend): -cd backend -npm install +#### Terminal 1: Backend Service +```bash +cd backend +npm install npm run dev Terminal 2 (frontend): 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 diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md new file mode 100644 index 0000000..9040f7e --- /dev/null +++ b/docs/DEPLOY.md @@ -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. diff --git a/docs/GUIDE-TO-K8S.md b/docs/GUIDE-TO-K8S.md new file mode 100644 index 0000000..e55b6a4 --- /dev/null +++ b/docs/GUIDE-TO-K8S.md @@ -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 --discovery-token-ca-cert-hash sha256: + +--- + +## 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\://: + +βœ… You now have a fully functional Kubernetes cluster on Ubuntu 24.04!