327 lines
15 KiB
Markdown
327 lines
15 KiB
Markdown
# VCH-Plattform — die Regeln dieser Umgebung
|
||
|
||
Diese Datei gehört VCH und wird bei jedem Abgleich **überschrieben**. Projektwissen gehört
|
||
in die `CLAUDE.md` daneben, nicht hierher.
|
||
|
||
Sie beschreibt, was VCH mit diesem Projekt macht — vor allem die Stellen, an denen ein
|
||
Verstoß **nicht als Fehler auffällt, sondern als falsches Ergebnis**: ein Deploy, der grün
|
||
meldet und nichts ausliefert, eine Datenbank, die niemand verbindet, ein Audit, das etwas
|
||
prüft, das du gar nicht gepusht hast.
|
||
|
||
## 1. Zwei Maschinen, nicht eine
|
||
|
||
- **Hier (DEV):** ein Debian-LXC. Nutzer `vchuser`, Heimat `/home/vchuser`, Projekte unter
|
||
`/home/vchuser/projects/<name>`. code-server auf Port 8080, Claude Code als `claude`,
|
||
Git gegen Gitea vorkonfiguriert.
|
||
- **Dort (PROD):** eine **andere** Maschine. VCH klont dein Repository dorthin und startet es.
|
||
|
||
Daraus folgt die wichtigste Regel überhaupt: **VCH deployt und auditiert deinen gepushten
|
||
Commit, nie dein Arbeitsverzeichnis.** Nicht committete Änderungen existieren für Deploy,
|
||
Audit und Veröffentlichung nicht — auch dann nicht, wenn hier alles läuft.
|
||
|
||
## 2. Vorschau im Browser läuft über einen Proxy
|
||
|
||
Deine Entwicklungs-Server sind nicht direkt erreichbar. VCH erkennt lauschende Ports und
|
||
stellt zwei Wege bereit:
|
||
|
||
1. **Subdomain** (bevorzugt): `https://lxc<VMID>-<PORT>.<domain>/` — deine App liegt auf der
|
||
Wurzel, alles verhält sich normal.
|
||
2. **Pfad-Proxy** (Rückfallweg): `https://<host>/proxy/<instanz>/p/<port>/` — deine App liegt
|
||
hinter einem Pfadpräfix.
|
||
|
||
Damit beides funktioniert: **relative Pfade verwenden.**
|
||
|
||
- `css/style.css` ✅ — nicht `/css/style.css` ❌
|
||
- `fetch('api/daten')` ✅ — nicht `fetch('/api/daten')` ❌
|
||
- Wenn absolute Pfade unvermeidbar sind: `<base href="./">` in den `<head>`.
|
||
|
||
Rahmenwerke: **Vite** `base: './'` · **Create React App** `"homepage": "."` in der
|
||
`package.json` · **Next.js** Vorgabe belassen (Subdomain) oder `basePath` setzen (Pfad-Proxy)
|
||
· **Express** `express.static` genügt, solange das HTML relativ verweist.
|
||
|
||
## 3. Dateien, die VCH im Projektstamm liest
|
||
|
||
| Datei | Pflicht | Wozu |
|
||
|---|---|---|
|
||
| `README.md` | ja | Audit-Prüfung `readme` — blockiert die Veröffentlichung |
|
||
| `.vch-description` | ja | Audit-Prüfung `description`; der Text steht später im Showcase |
|
||
| `.env.example` | wenn die App Umgebungsvariablen liest | die **Deklaration** aller Variablen (Abschnitt 6) |
|
||
| `.vch/deploy.yaml` | wenn die Autoerkennung nicht reicht | wie gebaut und gestartet wird (Abschnitt 5) |
|
||
| `CLAUDE.md` | — | dein Projektwissen; VCH fasst sie nicht mehr an |
|
||
|
||
`README.md` muss beschreiben, **was** das Projekt tut, wie man es installiert, wie man es
|
||
startet und worauf es aufbaut. Die unveränderte Vorlage besteht die Prüfung nicht.
|
||
|
||
`.vch-description` ist **nicht technisch**: was das Projekt tut, welches Problem es löst,
|
||
für wen. Kein Technologie-Stapel, keine Installationsanleitung — die stehen im README.
|
||
Halte beide aktuell, wenn sich Zweck oder Aufbau ändern.
|
||
|
||
## 4. Der Port gehört VCH
|
||
|
||
VCH weist jedem Projekt auf der PROD-Maschine einen festen Port zu (Bereich `13000–13999`)
|
||
und hält ihn über alle Deploys hinweg stabil. Du wählst ihn nicht und stimmst dich mit
|
||
niemandem ab.
|
||
|
||
**Deine App MUSS auf `PORT` aus der Umgebung lauschen:**
|
||
|
||
- Node/Express: `app.listen(process.env.PORT || 3000)`
|
||
- Next.js: `next start` beachtet `PORT` von selbst
|
||
- Python: `gunicorn app:app -b 0.0.0.0:$PORT` bzw. `uvicorn main:app --port $PORT`
|
||
- Go/andere: den Wert aus der Umgebung lesen, nicht hartkodieren
|
||
|
||
Ein fest verdrahteter Port läuft hier und scheitert dort am Healthcheck. `PORT` und
|
||
`VCH_DATA_DIR` sind **VCH-eigene** Schlüssel: setzt du sie selbst — in `.env.example`, im
|
||
Env-Editor oder im Compose — wird dein Wert verworfen.
|
||
|
||
## 5. `.vch/deploy.yaml` — die vollständige Referenz
|
||
|
||
Ohne diese Datei versucht VCH, das Projekt selbst zu erkennen (Abschnitt 5.3). Reicht das
|
||
nicht, bricht der Deploy ab **und legt dir eine fertige Vorlage vor**, die du nur noch
|
||
committen musst.
|
||
|
||
### 5.1 Alle Felder
|
||
|
||
| Feld | Typ | Vorgabe | Bedeutung |
|
||
|---|---|---|---|
|
||
| `runtime` | `auto` \| `systemd` \| `docker` | `auto` | Wie gestartet wird. `auto`: Dockerfile oder Compose vorhanden → `docker`, sonst `systemd`. |
|
||
| `build` | Zeichenkette | — | Shell-Befehl im Release-Verzeichnis. **Nur `systemd`** — bei `docker` baut das Dockerfile. |
|
||
| `start` | Zeichenkette | — | Startbefehl des Dienstes. **Nur `systemd`.** Muss `$PORT` binden. |
|
||
| `port` | Ganzzahl 1–65535 | `3000` | **Nur `docker`:** der Port, auf dem deine App **im Container** lauscht. VCH bildet den zugewiesenen Host-Port darauf ab. |
|
||
| `health` | Pfad | `/` | Pfad, der 2xx oder 3xx liefert, sobald die App bereit ist. |
|
||
| `env` | Liste von Zeichenketten | `[]` | Zusätzliche Variablennamen, die VCH ausliefern soll. Wird mit den Schlüsseln aus `.env.example` vereinigt. |
|
||
| `compose` | Pfad | — | Welche Compose-Datei gilt, wenn mehrere gefunden werden. |
|
||
|
||
Unbekannte Felder und Tippfehler in `runtime` brechen den Deploy mit einer benannten
|
||
Fehlermeldung ab — sie werden nicht still ignoriert.
|
||
|
||
### 5.2 Beispiele
|
||
|
||
Node mit eigenem Build (systemd):
|
||
|
||
```yaml
|
||
runtime: systemd
|
||
build: "npm ci && npm run build"
|
||
start: "npm start"
|
||
health: /
|
||
```
|
||
|
||
Python (systemd) — beachte `$PORT` im Startbefehl:
|
||
|
||
```yaml
|
||
runtime: systemd
|
||
build: "python3 -m venv .venv && .venv/bin/pip install -r requirements.txt"
|
||
start: ".venv/bin/gunicorn app:app -b 0.0.0.0:$PORT"
|
||
health: /
|
||
```
|
||
|
||
Statische Seite (systemd) — irgendetwas muss lauschen:
|
||
|
||
```yaml
|
||
runtime: systemd
|
||
build: "npm ci && npm run build"
|
||
start: "python3 -m http.server $PORT --directory dist"
|
||
```
|
||
|
||
Monorepo, Code in einem Unterordner:
|
||
|
||
```yaml
|
||
runtime: systemd
|
||
build: "cd backend && npm ci && npm run build"
|
||
start: "cd backend && npm start"
|
||
```
|
||
|
||
Dockerfile:
|
||
|
||
```yaml
|
||
runtime: docker
|
||
port: 3000 # der Port INNERHALB des Containers
|
||
health: /
|
||
```
|
||
|
||
Mehrere Compose-Dateien im Repository:
|
||
|
||
```yaml
|
||
runtime: docker
|
||
compose: docker/compose.yaml
|
||
```
|
||
|
||
### 5.3 Was ohne die Datei passiert
|
||
|
||
In dieser Reihenfolge:
|
||
|
||
1. Ein echtes `Dockerfile` gewinnt → `runtime: docker` mit dem Image.
|
||
2. Eine Compose-Datei, die `${VCH_PORT}` veröffentlicht → Compose-Deploy.
|
||
3. Eine Compose-Datei, die **nur Infrastruktur** startet (Postgres, Redis, … und keinen
|
||
App-Dienst), wird als Entwicklungs-Beiwerk erkannt und **nicht** deployt — VCH sucht
|
||
weiter nach der Sprache.
|
||
4. Eine Compose-Datei mit App-Dienst, die `${VCH_PORT}` **nicht** veröffentlicht → Abbruch
|
||
mit Vorlage (Abschnitt 10).
|
||
5. `package.json` im Stamm: `build`-Skript → Build, `start`-Skript bzw. `main` → Start.
|
||
Paketmanager wird am Lockfile erkannt (`pnpm`/`yarn`/`npm`).
|
||
6. Alles andere — Python, PHP/Laravel, Go, reines Frontend ohne `start`, Code nur in
|
||
Unterordnern — endet mit einer passenden Vorlage zum Committen.
|
||
|
||
## 6. Umgebungsvariablen: `.env.example` ist die Deklaration
|
||
|
||
VCH liest keine Umgebungsvariablen aus deinem Code. **Was in einer Beispieldatei steht,
|
||
existiert; alles andere nicht.**
|
||
|
||
- Erkannte Dateinamen: `.env.example`, `.env.sample`, `.env.template` sowie dieselben ohne
|
||
führenden Punkt (`env.example`, …). Der erste Fund je Schlüssel gewinnt.
|
||
- Gesucht wird **im ganzen Repository** (ohne `node_modules`, `.git`, `dist`, `build`,
|
||
`.next`, `out`, `vendor`, `coverage`, `.turbo`), Stammdateien zuerst, höchstens 25 Dateien.
|
||
- Jede gefundene Beispieldatei bestimmt ein Ziel: `backend/.env.example` → VCH schreibt die
|
||
Produktionswerte nach `backend/.env`. Für Monorepos ist das der Weg, mehrere `.env` zu
|
||
bekommen.
|
||
|
||
**Was den Deploy blockiert:** ein Schlüssel, der **keinen Wert nennt** (`KEY=`) und für den
|
||
noch kein Produktionswert hinterlegt ist. Nicht blockierend sind:
|
||
|
||
```dotenv
|
||
API_URL=https://beispiel.test # Vorgabewert vorhanden
|
||
OPTIONAL_TOKEN="" # ausdrücklich leer erlaubt
|
||
FEATURE_FLAG= # optional
|
||
```
|
||
|
||
Der Marker muss direkt hinter dem `#` stehen (`# optional`); Fließtext, in dem das Wort
|
||
vorkommt, zählt nicht. Die Vorgabewerte sind **Hinweise für den Menschen** — in Produktion
|
||
wird nichts davon verwendet.
|
||
|
||
Im Zweifel:
|
||
|
||
```bash
|
||
grep -RhoE "process\.env\.[A-Z_]+" src/ | sort -u
|
||
```
|
||
|
||
und jeden Treffer in die `.env.example` schreiben.
|
||
|
||
**Bei Docker:** nur Variablen mit dem Präfix `NEXT_PUBLIC_`, `VITE_` oder `PUBLIC_` gehen als
|
||
`--build-arg` in den Build (sie sind ohnehin im Auslieferungsstand sichtbar) — dafür brauchst
|
||
du passende `ARG`-Zeilen im Dockerfile. Alle übrigen Werte kommen erst zur Laufzeit über
|
||
`--env-file` und landen nie im Image.
|
||
|
||
## 7. Datenbank
|
||
|
||
Deklariert deine App Verbindungsvariablen, bietet VCH eine verwaltete Datenbank an und trägt
|
||
die Werte **automatisch** in genau die Schlüssel ein, die du deklariert hast. Du musst deine
|
||
Variablennamen also nicht ändern — VCH erkennt sie.
|
||
|
||
**Erkannt wird** (Groß-/Kleinschreibung egal):
|
||
|
||
- Verbindungszeichenketten: `DATABASE_URL`, `DB_URL`, jeder Name auf `_DSN`
|
||
- Einzelteile mit Familienwort (`DB`, `DATABASE`, `POSTGRES`, `MYSQL`) plus Rolle:
|
||
`..._HOST`, `..._PORT`, `..._USER`/`..._USERNAME`, `..._PASSWORD`/`..._PASS`,
|
||
`..._NAME`/`..._DATABASE`/`..._DB`
|
||
- Die üblichen nackten Namen: `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`,
|
||
`MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE`, `POSTGRES_DB`
|
||
|
||
**Bewusst nicht erkannt** (und deshalb nie überschrieben):
|
||
|
||
- alles mit `ROOT` im Namen (`POSTGRES_ROOT_PASSWORD`, `MYSQL_ROOT_PASSWORD`) — das sind die
|
||
Zugangsdaten des Datenbankservers, nicht die deiner App
|
||
- `SENTRY_DSN` und verwandte Fehlermelder (`GLITCHTIP`, `BUGSNAG`, `ROLLBAR`, `AIRBRAKE`,
|
||
`RAYGUN`, `APPSIGNAL`) — ein DSN ist dort keine Datenbank
|
||
- `HISTORY_DB=/data/verlauf.sqlite` und Ähnliches: ein `..._DB` ohne Datenbank-Familienwort
|
||
im übrigen Namen gilt nicht als Verbindung
|
||
|
||
Die **Engine** (Postgres oder MySQL) leitet VCH aus deinen Schlüsselnamen und dem Schema in
|
||
`DATABASE_URL` ab; ist das mehrdeutig, entscheidest du im Projektarbeitsplatz.
|
||
|
||
**Bringt dein Compose seine eigene Datenbank mit**, startet VCH sie mit und bietet **keine**
|
||
zweite an. Achte dann selbst auf ein dauerhaftes Volume — ein Datenbankdienst ohne Volume
|
||
verliert seine Daten beim nächsten Neubau, und VCH warnt nur.
|
||
|
||
Eine Compose-Datei, die **nur** eine Datenbank startet, ist Entwicklungs-Beiwerk: sie läuft in
|
||
Produktion nicht mit. Nimm dort die verwaltete Datenbank.
|
||
|
||
## 8. Dauerhafte Daten: `VCH_DATA_DIR`
|
||
|
||
Jedes Release liegt in einem eigenen Verzeichnis und verschwindet wieder. Was überleben soll —
|
||
SQLite-Datei, Uploads, erzeugte Dateien — gehört in das Verzeichnis aus **`VCH_DATA_DIR`**.
|
||
|
||
```js
|
||
const datenVerzeichnis = process.env.VCH_DATA_DIR || './data';
|
||
```
|
||
|
||
VCH setzt die Variable bei allen Betriebsarten (bei Docker als Einhängepunkt `/data`). **Lies
|
||
sie zur Laufzeit**, schreibe den Pfad nirgends fest und trage sie nicht in `.env`-Dateien ein.
|
||
Ein Verzeichnis relativ zum Release (`./data`) ist beim nächsten Deploy weg.
|
||
|
||
Der Prüfling während des Audits (Abschnitt 9) bekommt diesen Speicher **nicht** — er läuft
|
||
gegen einen leeren. Das ist Absicht: zwei Prozesse dürfen nicht gleichzeitig auf dieselbe
|
||
SQLite-Datei schreiben.
|
||
|
||
## 9. Wie ein Deploy abläuft
|
||
|
||
```
|
||
Klonen → Bauen → Healthcheck (Prüfling) → Audit → Umschalten → Live
|
||
```
|
||
|
||
1. **Klonen.** VCH klont den Deploy-Branch auf die PROD-Maschine — genau den gepushten Stand.
|
||
2. **Torprüfung.** Fehlt ein blockierender Wert aus `.env.example` (Abschnitt 6), endet es hier,
|
||
bevor irgendetwas läuft.
|
||
3. **Bauen** nach `.vch/deploy.yaml` bzw. Autoerkennung.
|
||
4. **Healthcheck.** Der neue Stand startet als **Prüfling** auf einem freien Port aus dem
|
||
Bereich `14000–14999`, neben der weiterhin laufenden alten Fassung. VCH ruft dort deinen
|
||
`health`-Pfad auf: rund 30 Sekunden lang, alle 1,5 s ein Versuch, Erfolg beim ersten
|
||
2xx/3xx. Bis dahin muss die App antworten.
|
||
5. **Audit** (Abschnitt 10) gegen den deployten Commit.
|
||
6. **Umschalten.** Erst wenn das Audit besteht, wird der Prüfling zur laufenden Fassung auf
|
||
dem stabilen Port. **Ein durchgefallenes Audit heißt: der alte Stand bleibt live.**
|
||
|
||
Vor dem Umschalten legt VCH einen Datenschnappschuss an. Geht das Umschalten schief, werden
|
||
erst die Daten und dann der Code zurückgerollt. Frühere Releases lassen sich im
|
||
Projektarbeitsplatz per Rollback zurückholen.
|
||
|
||
**Auto-Deploy:** ist er eingeschaltet, löst jeder Push auf den konfigurierten Deploy-Branch
|
||
einen Deploy aus. Pushes auf andere Branches werden ignoriert.
|
||
|
||
## 10. Audit — was geprüft wird
|
||
|
||
Das Audit läuft nicht hier, sondern in einem eigenen Runner gegen einen **sauberen Checkout
|
||
des deployten Commits**. Nicht Gepushtes wird nicht geprüft — und ein `.gitignore`-Eintrag
|
||
macht eine Datei für das Audit unsichtbar.
|
||
|
||
| Prüfung | Schwere | Darf entfallen |
|
||
|---|---|---|
|
||
| `readme` | Fehler | nein |
|
||
| `secrets` | Fehler | nein |
|
||
| `description` | Warnung | nein |
|
||
| `lint` | Fehler | ja |
|
||
| `typescript` | Fehler | ja |
|
||
| `npm-audit` | Fehler | ja |
|
||
|
||
- Eine **Warnung** blockiert nie. `description` hält dich also nicht auf, kostet dich aber den
|
||
Platz im Showcase.
|
||
- „Darf entfallen" heißt: die Prüfung meldet `skipped`, wenn sie auf dein Projekt nicht passt
|
||
(kein TypeScript, kein npm). Eine Prüfung, die **nicht** entfallen darf, aber trotzdem
|
||
`skipped` meldet, gilt als **durchgefallen** — sie ist nie gelaufen.
|
||
- `secrets` sucht eingecheckte Zugangsdaten. Echte Werte gehören nie ins Repository: in die
|
||
`.env.example` nur Beispiele, die echten Werte in den Env-Editor von VCH.
|
||
|
||
## 11. Veröffentlichen
|
||
|
||
- **Intern erreichbar** ist dein Projekt, sobald ein Deploy läuft — ohne Audit, ohne weiteren
|
||
Schritt, unter `http://<prod-ip>:<port>`.
|
||
- **Öffentlich** unter einer Subdomain mit SSL wird es erst mit laufendem Deploy **und**
|
||
bestandenem Audit für genau diesen Deploy. Die Subdomain kommt oben drauf; entfernst du sie
|
||
wieder, bleibt das Projekt intern erreichbar.
|
||
- Im **Showcase** erscheinen veröffentlichte Projekte mit bestandenem Audit und einer
|
||
eingecheckten `.vch-description`.
|
||
|
||
## 12. Compose — die vier Regeln, an denen es sonst scheitert
|
||
|
||
1. **Der App-Dienst muss seinen Port als `ports: ["${VCH_PORT}:<intern>"]` veröffentlichen.**
|
||
VCH setzt `VCH_PORT` und kann so einen Prüfling neben deiner laufenden Fassung starten.
|
||
Ohne diese Zeile bricht der Deploy ab.
|
||
2. **VCH führt genau EINE Compose-Datei aus — keine `-f`-Ketten.** Gesucht wird
|
||
`compose.yaml`/`compose.yml`/`docker-compose.yaml`/`docker-compose.yml` im Stamm **oder in
|
||
einem Unterordner**. Eine Override-Datei (`docker-compose.ports.yml`, `*.override.yml`)
|
||
wird **ignoriert** — die `${VCH_PORT}`-Zeile gehört in die Hauptdatei. Bei mehreren
|
||
Fundstellen: `compose: <pfad>` in die `.vch/deploy.yaml`.
|
||
3. **Jeder Dienst, der Produktionswerte braucht, bekommt `env_file: [.env]`.** VCH schreibt
|
||
deine Werte in eine `.env` neben der Compose-Datei.
|
||
4. **Der ganze Stapel startet.** Datenbanken, Caches und Ähnliches aus deinem Compose laufen
|
||
automatisch mit — eine zusätzliche verwaltete Datenbank brauchst du dafür nicht. Dienste
|
||
hinter einem `profiles:`-Schlüssel bleiben aus.
|