docs(cannamanage): update wiki pages and sprint plans + brand pipeline doc
This commit is contained in:
Patrick Plate
@@ -3,7 +3,7 @@
|
||||
**Project:** CannaManage — B2B SaaS for German Cannabis Social Clubs
|
||||
**Version:** 0.1.0-PLAN
|
||||
**Date:** 2026-04-06
|
||||
**Target environment:** Hetzner VPS — Ubuntu 22.04 LTS — Docker Compose
|
||||
**Target environment:** Hetzner VPS — Ubuntu 22.04 LTS — Docker Compose (Release) | TrueNAS.local — Docker (Build/CI)
|
||||
|
||||
---
|
||||
|
||||
@@ -45,20 +45,42 @@ Wildcard A record enables future per-club subdomains (`clubname.cannamanage.de`)
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Internet["🌐 Internet"] -->|"port 80/443"| Nginx["Nginx (reverse proxy)"]
|
||||
Nginx -->|"http://app:8080"| App["cannamanage-app\n(Spring Boot 3.x)"]
|
||||
App -->|"jdbc:postgresql://db:5432"| DB["PostgreSQL 16\n(cannamanage DB)"]
|
||||
LetsEncrypt["Let's Encrypt\n(certbot auto-renew)"] -.->|"TLS cert"| Nginx
|
||||
Gitea["Gitea Actions\n(homelab CI)"] -->|"SSH + docker compose"| VPS["Hetzner VPS\n/opt/cannamanage"]
|
||||
Dev["👨💻 Dev Workstation\n(Fedora, 192.168.188.x)"]
|
||||
Gitea["🏠 Gitea\n(truenas.local:30008)"]
|
||||
TrueNAS["🖧 TrueNAS.local Docker\n(192.168.188.119)\nBuild + Staging"]
|
||||
Hetzner["☁️ Hetzner VPS CX21\nProduction Release"]
|
||||
|
||||
subgraph VPS ["Hetzner VPS — Docker network: cannamanage_net"]
|
||||
Nginx
|
||||
App
|
||||
DB
|
||||
Dev -->|"git push"| Gitea
|
||||
Gitea -->|"Gitea Actions runner\n(on TrueNAS.local)"| TrueNAS
|
||||
TrueNAS -->|"mvn package + docker build"| TrueNAS
|
||||
TrueNAS -->|"docker save | scp\n(on merge to main)"| Hetzner
|
||||
|
||||
subgraph TrueNAS ["TrueNAS.local — CI/CD Build Environment"]
|
||||
GiteaRunner["Gitea Actions Runner"]
|
||||
BuildCache["Maven .m2 cache\n(persistent volume)"]
|
||||
StagingDB["PostgreSQL staging\n(ephemeral)"]
|
||||
end
|
||||
|
||||
subgraph Hetzner ["Hetzner VPS — Production Release Environment"]
|
||||
Nginx["Nginx (reverse proxy + TLS)"]
|
||||
App["cannamanage-app\n(Spring Boot 3.x)"]
|
||||
DB["PostgreSQL 16\n(persistent pgdata volume)"]
|
||||
Nginx -->|"proxy_pass :8080"| App
|
||||
App -->|"JDBC :5432"| DB
|
||||
end
|
||||
|
||||
Internet["🌍 Internet HTTPS"] -->|"port 443"| Nginx
|
||||
```
|
||||
|
||||
All three services run on an internal Docker bridge network (`cannamanage_net`). Only Nginx is exposed to the public internet. PostgreSQL has no external port binding.
|
||||
### Environment Roles
|
||||
|
||||
| Environment | Host | Purpose |
|
||||
|---|---|---|
|
||||
| **Development** | Dev workstation (Fedora) | Local feature development, unit tests |
|
||||
| **Build / CI** | TrueNAS.local Docker | Gitea Actions runner; Maven build; integration tests (Testcontainers); Docker image build |
|
||||
| **Production / Release** | Hetzner VPS CX21 | Live clubs, real data; Hetzner = our release environment |
|
||||
|
||||
All three services on Hetzner run on an internal Docker bridge network (`cannamanage_net`). Only Nginx is exposed to the public internet. PostgreSQL has no external port binding.
|
||||
|
||||
---
|
||||
|
||||
@@ -351,12 +373,14 @@ curl https://app.cannamanage.de/actuator/health
|
||||
|
||||
---
|
||||
|
||||
## 6. CI/CD Pipeline (Gitea Actions)
|
||||
## 6. CI/CD Pipeline (Gitea Actions on TrueNAS.local)
|
||||
|
||||
The Gitea Actions runner runs **on TrueNAS.local** — this is our homelab build machine. It has Docker, a persistent Maven `.m2` cache volume, and direct SSH access to the Hetzner VPS. Builds happen locally; only the final artifact (Docker image tarball) is shipped to Hetzner.
|
||||
|
||||
**File:** `.gitea/workflows/deploy.yml`
|
||||
|
||||
```yaml
|
||||
name: Deploy to Production
|
||||
name: Build and Deploy to Production
|
||||
|
||||
on:
|
||||
push:
|
||||
@@ -365,7 +389,7 @@ on:
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
runs-on: self-hosted # <-- TrueNAS.local Gitea runner
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
@@ -381,25 +405,18 @@ jobs:
|
||||
|
||||
- name: Run integration tests
|
||||
run: ./mvnw verify -P integration-tests
|
||||
# Testcontainers requires Docker — GitHub/Gitea hosted runners have Docker pre-installed
|
||||
# Testcontainers starts PostgreSQL via Docker on the TrueNAS runner
|
||||
|
||||
- name: Coverage gate check
|
||||
run: ./mvnw verify -P coverage-check
|
||||
|
||||
build-and-deploy:
|
||||
needs: test
|
||||
runs-on: ubuntu-latest
|
||||
runs-on: self-hosted # <-- TrueNAS.local Gitea runner
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up JDK 21
|
||||
uses: actions/setup-java@v4
|
||||
with:
|
||||
java-version: '21'
|
||||
distribution: 'temurin'
|
||||
cache: maven
|
||||
|
||||
- name: Build JAR
|
||||
- name: Build JAR (production profile)
|
||||
run: ./mvnw package -DskipTests -P production
|
||||
|
||||
- name: Build Docker image
|
||||
@@ -412,13 +429,13 @@ jobs:
|
||||
- name: Save Docker image
|
||||
run: docker save cannamanage:${{ github.sha }} | gzip > /tmp/cannamanage.tar.gz
|
||||
|
||||
- name: Copy image to VPS
|
||||
- name: Copy image to Hetzner VPS
|
||||
run: |
|
||||
scp -o StrictHostKeyChecking=no \
|
||||
/tmp/cannamanage.tar.gz \
|
||||
deploy@${{ secrets.HETZNER_IP }}:/tmp/cannamanage.tar.gz
|
||||
|
||||
- name: Deploy via SSH
|
||||
- name: Deploy via SSH to Hetzner (Production Release)
|
||||
run: |
|
||||
ssh -o StrictHostKeyChecking=no deploy@${{ secrets.HETZNER_IP }} "
|
||||
set -e
|
||||
@@ -435,23 +452,43 @@ jobs:
|
||||
sleep 10
|
||||
docker compose ps app | grep 'healthy' || (docker compose logs app --tail=50 && exit 1)
|
||||
|
||||
# Prune old images (keep last 3)
|
||||
# Prune old images (keep last 3 SHAs)
|
||||
docker image prune -f
|
||||
"
|
||||
|
||||
- name: Cleanup local build artifact
|
||||
run: rm -f /tmp/cannamanage.tar.gz
|
||||
```
|
||||
|
||||
### Gitea Actions Runner on TrueNAS.local
|
||||
|
||||
The self-hosted runner is a Docker container on TrueNAS.local:
|
||||
|
||||
```bash
|
||||
# On TrueNAS.local — install Gitea Actions runner
|
||||
docker run -d \
|
||||
--name gitea-runner-cannamanage \
|
||||
--restart unless-stopped \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-v /opt/gitea-runner/cannamanage:/data \
|
||||
-v /opt/gitea-runner/.m2:/root/.m2 \ # Maven cache persisted across builds
|
||||
-e GITEA_INSTANCE_URL=http://192.168.188.119:30008 \
|
||||
-e GITEA_RUNNER_REGISTRATION_TOKEN=<token-from-gitea-settings> \
|
||||
gitea/act_runner:latest
|
||||
```
|
||||
|
||||
### Required Gitea Repository Secrets
|
||||
|
||||
| Secret | Value |
|
||||
|--------|-------|
|
||||
| `HETZNER_IP` | VPS IPv4 address |
|
||||
| `SSH_PRIVATE_KEY` | Private key for `deploy` user |
|
||||
| Secret | Where set | Value |
|
||||
|--------|-----------|-------|
|
||||
| `HETZNER_IP` | Gitea repo secrets | Hetzner VPS IPv4 address |
|
||||
| `SSH_PRIVATE_KEY` | Gitea repo secrets | Private key for `deploy` user on Hetzner |
|
||||
|
||||
Add deploy user's public key to VPS authorized_keys:
|
||||
```bash
|
||||
# On VPS as deploy user
|
||||
# On Hetzner VPS — add TrueNAS runner's public key
|
||||
# (generate keypair on TrueNAS.local: ssh-keygen -t ed25519 -f ~/.ssh/gitea_runner_deploy)
|
||||
mkdir -p ~/.ssh && chmod 700 ~/.ssh
|
||||
echo "<gitea-actions-public-key>" >> ~/.ssh/authorized_keys
|
||||
echo "<truenas-runner-public-key>" >> ~/.ssh/authorized_keys
|
||||
chmod 600 ~/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user