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 <noreply@anthropic.com>

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: <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
+    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
+
+networks:
+  nginx-proxy-manager_default:
+    external: true
+
+volumes:
+  <app>-data:
+    # Fester Name, damit das Volume nicht am Projektnamen haengt.
+    name: <app>-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 <port>` 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 | `<app>.lucas-orth.de` |
+| Scheme | `http` |
+| Forward Hostname / IP | `<app>`  (= `container_name`) |
+| Forward Port | `<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=<app>`). 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 |

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 -- <app-name> <port>
+```
+
+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 <app-name> <port>
+```
+
+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=<gitea-pat-mit-read-scope> sh bootstrap.sh <app-name> <port>
+```

bootstrap.sh

@@ -0,0 +1,61 @@
+#!/bin/sh
+# Holt die Deployment-Dateien in ein neues Projekt.
+#
+#   sh bootstrap.sh <app-name> <port>
+#
+# Vorhandene Dateien werden nicht ueberschrieben, nur fehlende angelegt.
+# Bei privatem Repo: DEPLOY_KIT_TOKEN=<gitea-pat> 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 <app-name> <port>" >&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 <<EOF
+
+Fertig. Noch zu tun:
+
+  1. Dockerfile an den Stack anpassen (die Vorlage ist fuer Node).
+  2. Build- und Test-Schritte in .gitea/workflows/deploy.yml einkommentieren.
+  3. Healthcheck in docker-compose.yml auf den echten Endpoint zeigen lassen.
+  4. Repo-Secret DOTENV in Gitea anlegen.
+  5. Proxy Host im NPM: $APP.lucas-orth.de -> $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

template/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.git
+.gitea
+dist
+*.log
+.env

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

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"]

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