From f5bdb9a988c158c2a6219c715d1dea2a8f04a7c9 Mon Sep 17 00:00:00 2001 From: Lucas Orth Date: Thu, 20 Aug 2026 19:29:31 +0200 Subject: [PATCH] deploy-kit zum Gitea-Template-Repo umbauen Statt eines zweiten Repos wird deploy-kit selbst die Vorlage. Ein Template kopiert das gesamte Repo, die Projektdateien muessen also im Wurzel- verzeichnis liegen - template/ ist entsprechend aufgeloest. - bootstrap.sh entfaellt: das Template uebernimmt seine Aufgabe, und Gitea kopiert serverseitig, funktioniert also auch bei privatem Repo. - .gitea/template laesst Gitea ${REPO_NAME} in README.md und docker-compose.yml ersetzen. Projektname, Image und container_name stimmen damit ohne Handarbeit, offen bleibt nur der Port. - CLAUDE.md zeigt auf DEPLOY.md, damit die Konventionen beim Arbeiten am erzeugten Projekt gelesen werden. - DEPLOY.md liegt jetzt nur noch einmal - die Kopie im geplanten zweiten Repo waere unweigerlich auseinandergelaufen. Co-Authored-By: Claude Opus 5 --- template/.dockerignore => .dockerignore | 0 .gitea/template | 2 + .../.gitea => .gitea}/workflows/deploy.yml | 0 CLAUDE.md | 24 ++++++ template/Dockerfile => Dockerfile | 0 MIGRATION.md | 4 +- README.md | 80 +++++++++---------- bootstrap.sh | 61 -------------- .../docker-compose.yml => docker-compose.yml | 10 +-- 9 files changed, 70 insertions(+), 111 deletions(-) rename template/.dockerignore => .dockerignore (100%) create mode 100644 .gitea/template rename {template/.gitea => .gitea}/workflows/deploy.yml (100%) create mode 100644 CLAUDE.md rename template/Dockerfile => Dockerfile (100%) delete mode 100755 bootstrap.sh rename template/docker-compose.yml => docker-compose.yml (87%) diff --git a/template/.dockerignore b/.dockerignore similarity index 100% rename from template/.dockerignore rename to .dockerignore diff --git a/.gitea/template b/.gitea/template new file mode 100644 index 0000000..83e3d09 --- /dev/null +++ b/.gitea/template @@ -0,0 +1,2 @@ +README.md +docker-compose.yml diff --git a/template/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml similarity index 100% rename from template/.gitea/workflows/deploy.yml rename to .gitea/workflows/deploy.yml diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e1bf6de --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,24 @@ +# Projekthinweise + +## Deployment + +Diese App wird per Tag-Push deployt, nicht manuell hochgeladen. +Die verbindlichen Konventionen stehen in **DEPLOY.md**. Vor Aenderungen an +`Dockerfile`, `docker-compose.yml` oder `.gitea/workflows/` dort nachsehen. + +Kurzfassung der Regeln, die man leicht bricht: + +- Kein `ports:` im Compose. Der Proxy erreicht den Container ueber das Netz + `nginx-proxy-manager_default` unter seinem `container_name`. +- `name:` im Compose ist Pflicht (fester Projektname), sonst legt der + CI-Job einen zweiten Stack an. +- Keine relativen Bind-Mounts. Compose laeuft im Job-Container, der Pfad + zeigt auf dem Host ins Leere. Persistente Daten in named volumes mit + festem `name:`. +- Healthcheck ist Pflicht, der Deploy nutzt ihn als Gate. +- Secrets kommen aus dem Repo-Secret `DOTENV`, nie in die Compose-Datei. + +## Noch offen in diesem Repo + +Nach dem Anlegen aus der Vorlage sind `__APP__` und `__PORT__` zu ersetzen +und das Dockerfile an den Stack anzupassen. Details in README.md. diff --git a/template/Dockerfile b/Dockerfile similarity index 100% rename from template/Dockerfile rename to Dockerfile diff --git a/MIGRATION.md b/MIGRATION.md index 230d8dc..ba3c5ab 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -59,11 +59,11 @@ Falls der Code bisher nur auf dem Server lag: per SCP herunterholen, **ohne** | kein `healthcheck:` | einen ergaenzen | Der Deploy nutzt `--wait` und macht ihn zum Gate | | relative Bind-Mounts `./x:/x` | named volume | Compose laeuft im Job-Container, der Pfad zeigt ins Leere | -Vorlage: [template/docker-compose.yml](template/docker-compose.yml). +Vorlage: [docker-compose.yml](docker-compose.yml). ## Schritt 3: Workflow anlegen -[template/.gitea/workflows/deploy.yml](template/.gitea/workflows/deploy.yml) +[.gitea/workflows/deploy.yml](.gitea/workflows/deploy.yml) uebernehmen, Build- und Test-Schritte des Projekts einsetzen. Tests gehoeren **vor** den Deploy-Schritt. diff --git a/README.md b/README.md index fcf8454..02269fa 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,55 @@ -# deploy-kit +# ${REPO_NAME} -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). +Aus der Vorlage +[deploy-kit](https://gitea.lucas-orth.de/lucas.orth/deploy-kit) erzeugt. -## In ein neues Projekt holen +## Einrichten + +**1. Port setzen.** Den App-Namen hat Gitea beim Anlegen aus dem +Repo-Namen eingesetzt. Offen ist nur noch der Port: ```bash -curl -fsSL https://gitea.lucas-orth.de/lucas.orth/deploy-kit/raw/branch/main/bootstrap.sh | sh -s -- +sed -i "s/__PORT__/3000/g" docker-compose.yml Dockerfile ``` -Oder erst herunterladen und ansehen, dann ausfuehren: +Auf den Port anpassen, auf dem die App tatsaechlich lauscht. + +**2. Dockerfile anpassen.** Die Vorlage ist fuer Node mit TypeScript-Build. + +**3. Build- und Test-Schritte** in `.gitea/workflows/deploy.yml` +einkommentieren. + +**4. Healthcheck** in `docker-compose.yml` auf einen echten Endpoint zeigen +lassen. Er ist das Gate des Deploy-Schritts - zeigt er ins Leere, schlaegt +jeder Deploy fehl. + +**5. Secret `DOTENV`** anlegen: Einstellungen -> Actions -> Secrets, mit dem +kompletten `.env`-Inhalt, mehrzeilig. + +**6. Proxy Host** im Nginx Proxy Manager: +`${REPO_NAME}.lucas-orth.de` -> `${REPO_NAME}` : Port aus Schritt 1. + +**7. Deployen:** ```bash -curl -fsSLO https://gitea.lucas-orth.de/lucas.orth/deploy-kit/raw/branch/main/bootstrap.sh && sh bootstrap.sh +git tag v1.0.0 && git push origin v1.0.0 ``` -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. - -## Bestehende App umstellen - -Fuer Apps, die heute per SCP deployt werden, gibt es eine eigene Anleitung - -inklusive Volume-Migration, damit der Wechsel des Projektnamens keine Daten -kostet: +## Pruefen, bevor der erste Tag faellt ```bash -curl -fsSL -o MIGRATION.md https://gitea.lucas-orth.de/lucas.orth/deploy-kit/raw/branch/main/MIGRATION.md +grep -n '__APP__\|__PORT__\|\${REPO_NAME}' docker-compose.yml Dockerfile ``` -Dann Claude bitten, die Schritte darin auf das Projekt anzuwenden. +Kein Treffer heisst: alles ersetzt. -## Nur die Konventionen +Falls in `docker-compose.yml` `${IMAGE_TAG:-latest}` verstuemmelt ist, hat +die Template-Ersetzung zu viel angefasst - dann `docker-compose.yml` aus +`.gitea/template` streichen und die Platzhalter von Hand setzen. -Wenn ein Projekt schon eingerichtet ist und du nur die aktuelle Fassung der -Regeln brauchst: +## Konventionen -```bash -curl -fsSL -o DEPLOY.md https://gitea.lucas-orth.de/lucas.orth/deploy-kit/raw/branch/main/DEPLOY.md -``` +**DEPLOY.md** - verbindlich, liegt im Projekt. -## 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 -``` +**MIGRATION.md** gilt nur, wenn diese App vorher schon manuell auf dem +Server lief. Bei einem neuen Projekt kann die Datei geloescht werden. diff --git a/bootstrap.sh b/bootstrap.sh deleted file mode 100755 index b5f4365..0000000 --- a/bootstrap.sh +++ /dev/null @@ -1,61 +0,0 @@ -#!/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/docker-compose.yml b/docker-compose.yml similarity index 87% rename from template/docker-compose.yml rename to docker-compose.yml index 6cb6d3a..435be25 100644 --- a/template/docker-compose.yml +++ b/docker-compose.yml @@ -1,14 +1,14 @@ # 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__ +name: ${REPO_NAME} services: app: # Versionstag ermoeglicht Rollback ohne Rebuild. - image: __APP__:${IMAGE_TAG:-latest} + image: ${REPO_NAME}:${IMAGE_TAG:-latest} build: . # Fester Name: das ist die Adresse, auf die der Proxy zeigt. - container_name: __APP__ + container_name: ${REPO_NAME} restart: unless-stopped # Wird im Workflow aus dem Secret DOTENV erzeugt. env_file: .env @@ -31,5 +31,5 @@ networks: # 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 +# ${REPO_NAME}-data: +# name: ${REPO_NAME}-data