From eeb4477476bfbfd0ba53e5dbe4b76a8a9a14f340 Mon Sep 17 00:00:00 2001 From: Lucas Orth Date: Thu, 20 Aug 2026 19:18:06 +0200 Subject: [PATCH] Deployment-Konventionen und Projektvorlagen DEPLOY.md beschreibt, wie ein Container aussehen muss, damit er mit dem Runner und dem Nginx Proxy Manager zusammenspielt: fester Projektname, Image mit Versionstag, kein ports-Mapping, Healthcheck als Deploy-Gate, named volumes statt relativer Bind-Mounts. bootstrap.sh holt die Vorlagen per curl in ein neues Projekt und ersetzt __APP__ und __PORT__. Vorhandene Dateien bleiben unangetastet. Co-Authored-By: Claude Opus 5 --- DEPLOY.md | 181 +++++++++++++++++++++++++++ README.md | 49 ++++++++ bootstrap.sh | 61 +++++++++ template/.dockerignore | 6 + template/.gitea/workflows/deploy.yml | 50 ++++++++ template/Dockerfile | 17 +++ template/docker-compose.yml | 35 ++++++ 7 files changed, 399 insertions(+) create mode 100644 DEPLOY.md create mode 100644 README.md create mode 100755 bootstrap.sh create mode 100644 template/.dockerignore create mode 100644 template/.gitea/workflows/deploy.yml create mode 100644 template/Dockerfile create mode 100644 template/docker-compose.yml diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000..2e43c1c --- /dev/null +++ b/DEPLOY.md @@ -0,0 +1,181 @@ +# Deployment-Konventionen + +Verbindlich fuer jede App, die auf dem VPS per Tag-Push deployt wird. +Abweichungen brauchen einen Grund, der hier nicht steht. + +## Ablauf + +``` +git tag v1.2.3 && git push --tags + -> Gitea Actions (act_runner auf dem VPS) + -> npm ci / build / test <- rot bricht ab, nichts wird deployt + -> .env aus Repo-Secret DOTENV + -> docker compose up -d --build --wait +``` + +Kein SCP, kein manuelles Neubauen. Der Code landet nie im Dateisystem des +Hosts - der Job-Container klont, baut gegen den Docker-Daemon des Hosts und +startet den Container. + +## Infrastruktur (existiert bereits, nicht neu anlegen) + +| Ding | Wert | +|---|---| +| Git | Gitea, `https://gitea.lucas-orth.de`, Container `gitea`, intern `:3000` | +| Runner | `act_runner`, Container `gitea-runner`, Label `ubuntu-latest` | +| Netz CI | `gitea-ci` - Gitea + Runner + Job-Container | +| Netz Web | `nginx-proxy-manager_default` - Proxy + alle App-Container | +| Job-Image | `catthehacker/ubuntu:act-latest` (node + docker-cli + compose) | + +Die beiden Netze sind bewusst getrennt: der Runner spricht mit Gitea, nicht +mit dem Proxy. App-Container haengen im Web-Netz, nicht im CI-Netz. + +## docker-compose.yml + +```yaml +# Fester Projektname. Ohne das leitet Compose ihn aus dem Verzeichnisnamen +# ab - und der ist im CI-Job ein anderer als auf dem Host. +name: + +services: + app: + # Versionstag ermoeglicht Rollback ohne Rebuild. + image: :${IMAGE_TAG:-latest} + build: . + # Fester Name: das ist die Adresse, auf die der Proxy zeigt. + container_name: + restart: unless-stopped + # Wird im Workflow aus dem Secret DOTENV erzeugt. + env_file: .env + networks: + - nginx-proxy-manager_default + healthcheck: + test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"] + interval: 60s + timeout: 5s + retries: 3 + +networks: + nginx-proxy-manager_default: + external: true + +volumes: + -data: + # Fester Name, damit das Volume nicht am Projektnamen haengt. + name: -data +``` + +**Kein `ports:`.** Der Proxy erreicht den Container ueber das gemeinsame Netz +unter seinem Container-Namen. Ein Port-Mapping wuerde den Dienst zusaetzlich +offen ans Internet haengen. + +**Healthcheck ist Pflicht.** Der Deploy-Schritt nutzt `--wait` und macht ihn +zum Gate. Ohne Healthcheck wird der Lauf gruen, auch wenn der Container in +einer Crash-Schleife haengt. + +**Keine relativen Bind-Mounts** (`./data:/data`). Compose laeuft im +Job-Container, der Pfad wuerde auf dem Host ins Leere zeigen. Persistente +Daten gehoeren in ein named volume mit festem `name:`. + +## .gitea/workflows/deploy.yml + +```yaml +name: Build & Deploy + +on: + push: + tags: + - 'v*' + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + # Intern klonen. Die oeffentliche Domain ist aus Containern heraus + # NICHT erreichbar: Gitea laeuft auf demselben Host, das Paket geht + # an die oeffentliche IP und findet nicht zurueck (NAT-Hairpin). + - uses: actions/checkout@v4 + with: + github-server-url: http://gitea:3000 + + # --- Build & Tests, projektspezifisch --- + + - name: Tag ermitteln + run: echo "IMAGE_TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV + + - name: .env aus Secret erzeugen + env: + DOTENV: ${{ secrets.DOTENV }} + run: | + if [ -z "$DOTENV" ]; then + echo "Secret DOTENV ist leer oder nicht gesetzt." + exit 1 + fi + umask 077 + echo "$DOTENV" > .env + + - name: Deployen + run: docker compose up -d --build --remove-orphans --wait --wait-timeout 180 + + - name: Alte Layer aufraeumen + run: docker image prune -f +``` + +Tests gehoeren **vor** den Deploy-Schritt. Ein roter Lauf darf den Server +nicht anfassen. + +## Dockerfile + +- Multi-Stage: Build-Abhaengigkeiten landen nicht im finalen Image. +- `USER node` bzw. non-root im finalen Stage. +- `EXPOSE ` dokumentiert den internen Port (oeffnet nichts). +- Ein Health-Endpoint (`/healthz`), auf den der Healthcheck zeigt. + +## Secrets + +Ein einziges Repo-Secret **`DOTENV`** mit dem kompletten `.env`-Inhalt, +mehrzeilig. Anlegen unter Repo -> Einstellungen -> Actions -> Secrets. + +Gitea speichert Secrets write-only: nach dem Anlegen nicht mehr lesbar, nur +ersetzbar. Die kanonische Fassung gehoert deshalb in den Passwortmanager, +Gitea haelt nur die Arbeitskopie fuer die Pipeline. + +Der Wert wird ueber `env:` an die Shell gereicht, nie direkt interpoliert - +sonst zerlegt der Shell-Parser Werte mit `$`, Backticks oder Quotes. + +## Nginx Proxy Manager + +Neuer Proxy Host: + +| Feld | Wert | +|---|---| +| Domain Names | `.lucas-orth.de` | +| Scheme | `http` | +| Forward Hostname / IP | `` (= `container_name`) | +| Forward Port | `` | + +Danach Let's-Encrypt-Zertifikat ausstellen und "Force SSL" aktivieren. + +Weil der Container-Name die Adresse ist: aendert sich `container_name`, +zeigt der Proxy-Host ins Leere. + +## Erstes Deployment einer App + +1. Repo in Gitea anlegen, pushen. +2. Secret `DOTENV` setzen. +3. Pruefen, ob schon ein Container mit dem Namen laeuft + (`docker ps -a --filter name=`). Falls ja: im alten Verzeichnis + einmal `docker compose down`, sonst kollidiert der feste Container-Name. +4. Proxy Host im NPM anlegen. +5. `git tag v1.0.0 && git push origin v1.0.0` + +## Fallstricke + +| Symptom | Ursache | +|---|---| +| Job haengt beim Checkout | `github-server-url` fehlt, klont ueber die oeffentliche Domain | +| `network not found` | App-Container im CI-Netz statt im Web-Netz (oder umgekehrt) | +| Zweiter Container statt Update | `name:` im Compose fehlt, Projektname weicht ab | +| Lauf gruen, App tot | `--wait` fehlt oder kein Healthcheck definiert | +| Volume leer nach Umstellung | Projektname geaendert, altes Volume hiess anders | +| Proxy liefert 502 | `container_name` geaendert oder Container nicht im Web-Netz | diff --git a/README.md b/README.md new file mode 100644 index 0000000..2f29302 --- /dev/null +++ b/README.md @@ -0,0 +1,49 @@ +# deploy-kit + +Vorlagen und Konventionen fuer Apps, die auf dem VPS per Tag-Push deployt +werden. Der Runner selbst liegt in +[gitea-runner](https://gitea.lucas-orth.de/lucas.orth/gitea-runner). + +## In ein neues Projekt holen + +```bash +curl -fsSL https://gitea.lucas-orth.de/lucas.orth/deploy-kit/raw/branch/main/bootstrap.sh | sh -s -- +``` + +Oder erst herunterladen und ansehen, dann ausfuehren: + +```bash +curl -fsSLO https://gitea.lucas-orth.de/lucas.orth/deploy-kit/raw/branch/main/bootstrap.sh && sh bootstrap.sh +``` + +Das Skript legt an, was fehlt, und laesst Vorhandenes unangetastet: + +| Datei | Zweck | +|---|---| +| `DEPLOY.md` | Die Konventionen. Fuer dich und fuer Claude. | +| `docker-compose.yml` | Projektname, Image-Tag, Web-Netz, Healthcheck | +| `.gitea/workflows/deploy.yml` | Tag `v*` -> Build -> Test -> Deploy | +| `.dockerignore` | | +| `Dockerfile` | Node-Vorlage, pro Projekt anzupassen | + +`__APP__` und `__PORT__` werden dabei ersetzt. + +## Nur die Konventionen + +Wenn ein Projekt schon eingerichtet ist und du nur die aktuelle Fassung der +Regeln brauchst: + +```bash +curl -fsSL -o DEPLOY.md https://gitea.lucas-orth.de/lucas.orth/deploy-kit/raw/branch/main/DEPLOY.md +``` + +## Sichtbarkeit + +Das Repo muss oeffentlich sein, damit `curl` ohne Umstaende funktioniert. +Es enthaelt keine Secrets - aber es beschreibt die Infrastruktur +(Domains, Netznamen, Containernamen). Wenn dir das zu viel ist, stell es auf +privat und setze beim Bootstrap ein Token: + +```bash +DEPLOY_KIT_TOKEN= sh bootstrap.sh +``` diff --git a/bootstrap.sh b/bootstrap.sh new file mode 100755 index 0000000..b5f4365 --- /dev/null +++ b/bootstrap.sh @@ -0,0 +1,61 @@ +#!/bin/sh +# Holt die Deployment-Dateien in ein neues Projekt. +# +# sh bootstrap.sh +# +# Vorhandene Dateien werden nicht ueberschrieben, nur fehlende angelegt. +# Bei privatem Repo: DEPLOY_KIT_TOKEN= vorher setzen. +set -eu + +BASE="${DEPLOY_KIT_BASE:-https://gitea.lucas-orth.de/lucas.orth/deploy-kit/raw/branch/main}" + +APP="${1:-}" +PORT="${2:-}" +if [ -z "$APP" ] || [ -z "$PORT" ]; then + echo "Aufruf: sh bootstrap.sh " >&2 + echo "Beispiel: sh bootstrap.sh busyfeed 8080" >&2 + exit 1 +fi + +fetch() { + remote="$1" + local_path="$2" + if [ -e "$local_path" ]; then + echo " uebersprungen, existiert: $local_path" + return 0 + fi + dir=$(dirname "$local_path") + [ "$dir" = "." ] || mkdir -p "$dir" + if [ -n "${DEPLOY_KIT_TOKEN:-}" ]; then + curl -fsSL -H "Authorization: token $DEPLOY_KIT_TOKEN" "$BASE/$remote" -o "$local_path" + else + curl -fsSL "$BASE/$remote" -o "$local_path" + fi + echo " angelegt: $local_path" +} + +fetch DEPLOY.md DEPLOY.md +fetch template/docker-compose.yml docker-compose.yml +fetch template/.gitea/workflows/deploy.yml .gitea/workflows/deploy.yml +fetch template/.dockerignore .dockerignore +fetch template/Dockerfile Dockerfile + +for f in docker-compose.yml Dockerfile; do + [ -f "$f" ] && sed -i "s/__APP__/$APP/g; s/__PORT__/$PORT/g" "$f" +done + +cat < $APP:$PORT + + Konventionen und Fallstricke: DEPLOY.md + Damit Claude sie liest, in CLAUDE.md eine Zeile ergaenzen: + Deployment-Konventionen stehen in DEPLOY.md. Vor Aenderungen an + Dockerfile, docker-compose.yml oder Workflows dort nachsehen. +EOF diff --git a/template/.dockerignore b/template/.dockerignore new file mode 100644 index 0000000..401ff02 --- /dev/null +++ b/template/.dockerignore @@ -0,0 +1,6 @@ +node_modules +.git +.gitea +dist +*.log +.env diff --git a/template/.gitea/workflows/deploy.yml b/template/.gitea/workflows/deploy.yml new file mode 100644 index 0000000..84c58d0 --- /dev/null +++ b/template/.gitea/workflows/deploy.yml @@ -0,0 +1,50 @@ +name: Build & Deploy + +on: + push: + tags: + - 'v*' + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + # Intern klonen statt ueber die oeffentliche Domain: Gitea laeuft auf + # demselben Host, der Weg ueber die oeffentliche IP findet nicht + # zurueck (NAT-Hairpin). Der Job-Container erreicht Gitea ueber das + # Netz gitea-ci unter seinem Containernamen. + - uses: actions/checkout@v4 + with: + github-server-url: http://gitea:3000 + + # --- Build & Tests: hier projektspezifisch anpassen --- + # - uses: actions/setup-node@v4 + # with: + # node-version: '24' + # - run: npm ci + # - run: npm run build + # - run: npm test + # ------------------------------------------------------ + + - name: Tag ermitteln + run: echo "IMAGE_TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV + + # Ein einziges Repo-Secret DOTENV mit dem kompletten .env-Inhalt + # (mehrzeilig). Ueber env: statt direkter Interpolation, damit + # Anfuehrungszeichen, Backticks und $ in den Werten unangetastet bleiben. + - name: .env aus Secret erzeugen + env: + DOTENV: ${{ secrets.DOTENV }} + run: | + if [ -z "$DOTENV" ]; then + echo "Secret DOTENV ist leer oder nicht gesetzt." + exit 1 + fi + umask 077 + echo "$DOTENV" > .env + + - name: Deployen + run: docker compose up -d --build --remove-orphans --wait --wait-timeout 180 + + - name: Alte Layer aufraeumen + run: docker image prune -f diff --git a/template/Dockerfile b/template/Dockerfile new file mode 100644 index 0000000..03d88ec --- /dev/null +++ b/template/Dockerfile @@ -0,0 +1,17 @@ +# Beispiel fuer eine Node-App. Pro Projekt anpassen. +FROM node:24-alpine AS build +WORKDIR /app +COPY package.json package-lock.json tsconfig.json ./ +RUN npm ci +COPY src ./src +RUN npm run build + +FROM node:24-alpine +WORKDIR /app +ENV NODE_ENV=production +COPY package.json package-lock.json ./ +RUN npm ci --omit=dev && npm cache clean --force +COPY --from=build /app/dist ./dist +USER node +EXPOSE __PORT__ +CMD ["node", "dist/server.js"] diff --git a/template/docker-compose.yml b/template/docker-compose.yml new file mode 100644 index 0000000..6cb6d3a --- /dev/null +++ b/template/docker-compose.yml @@ -0,0 +1,35 @@ +# Fester Projektname. Ohne das leitet Compose ihn aus dem Verzeichnisnamen +# ab - und der ist im CI-Job ein anderer als auf dem Host. +name: __APP__ + +services: + app: + # Versionstag ermoeglicht Rollback ohne Rebuild. + image: __APP__:${IMAGE_TAG:-latest} + build: . + # Fester Name: das ist die Adresse, auf die der Proxy zeigt. + container_name: __APP__ + restart: unless-stopped + # Wird im Workflow aus dem Secret DOTENV erzeugt. + env_file: .env + networks: + - nginx-proxy-manager_default + # Pflicht: der Deploy-Schritt nutzt --wait und macht das zum Gate. + # Auf den Health-Endpoint der App anpassen. + healthcheck: + test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:__PORT__/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"] + interval: 60s + timeout: 5s + retries: 3 + +# Kein ports-Mapping: Der Proxy erreicht den Container ueber das gemeinsame +# Netz unter seinem Container-Namen. +networks: + nginx-proxy-manager_default: + external: true + +# Persistente Daten nur als named volume mit festem Namen - relative +# Bind-Mounts zeigen aus dem Job-Container heraus ins Leere. +# volumes: +# __APP__-data: +# name: __APP__-data