diff --git a/README.md b/README.md index 4fb866c..5d1f15f 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,63 @@ fusero-app-boilerplate/ - Docker and Docker Compose - Git -## Development Setup +## πŸ—ƒοΈ Create Docker Volume for Postgres -### Important Note: Database Must Run in Docker +Before starting the database, create a Docker volume to persist Postgres data: +```sh +docker volume create fusero-db-data +``` + +## πŸ› οΈ Running Migrations and Seeding the Database in Kubernetes + +To run migrations and seed the database in your Kubernetes cluster, a job is included in the Helm chart. The job runs the following command: + +```sh +npx mikro-orm migration:up && npm run seed +``` + +This job is triggered automatically on deployment. If you need to rerun it manually, you can delete and recreate the job using kubectl. + +## πŸ’» Development Setup + +Backend setup: +- Copy the example environment file: + ```sh + cp backend/.env.example backend/.env + ``` +- Install dependencies: + ```sh + npm install + ``` +- Run migrations and seed: + ```sh + npm run migrate + npm run seed + ``` +- Start the backend in development mode: + ```sh + npm run dev & + ``` + +Frontend setup: +- Copy the example environment file: + ```sh + cp frontend/.env.example frontend/.env + ``` +- Install dependencies: + ```sh + npm install + ``` +- Start the frontend in development mode: + ```sh + npm run dev & + ``` + +App is running: +- Frontend β†’ http://localhost:3000 +- Backend β†’ http://localhost:14000 + +## 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: 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 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!