Florian WildeandClaude Opus 5
56b5356708
README mit Funktionsumfang, Bildergalerie, allen Umgebungsvariablen als Tabelle und dem Betrieb inklusive Sicherung und Wiederherstellung. Der Schnellstart führt in acht Schritten von git clone zur ersten Anmeldung, jeder Schritt mit erwartetem Ergebnis. Er endet mit dem Hinterlegen eines Passkeys statt beim ersten Kalenderkonto oder der ersten Aufgabe — beides gibt es erst mit M3 und M2. Das ist in ROADMAP und Handbuch so vermerkt, damit niemand danach sucht. Handbuch mit Seiten zu Anmelden, Bereichen und Protokoll. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
156 lines
6.7 KiB
Markdown
156 lines
6.7 KiB
Markdown
# Schnellstart
|
||
|
||
Von `git clone` bis zur ersten Anmeldung in höchstens zehn Minuten.
|
||
Jeder Befehl ist zum Kopieren, jeder Schritt nennt das erwartete Ergebnis.
|
||
|
||
## Voraussetzungen
|
||
|
||
| Werkzeug | Fassung | Prüfen mit |
|
||
| ------------------ | ---------------- | ------------------------ |
|
||
| Docker mit Compose | 25 oder neuer | `docker compose version` |
|
||
| Git | 2.40 oder neuer | `git --version` |
|
||
| Node.js | 22.12 oder neuer | `node -v` |
|
||
|
||
Node wird nur für die Entwicklung gebraucht. Für den reinen Betrieb genügen
|
||
Docker und Git.
|
||
|
||
## 1. Holen und Verzeichnis wechseln
|
||
|
||
```bash
|
||
git clone <REMOTE_URL> planer
|
||
cd planer
|
||
```
|
||
|
||
**Erwartet:** Das Verzeichnis `planer` enthält unter anderem `package.json`,
|
||
`docker-compose.yml` und `.env.example`.
|
||
|
||
## 2. Konfiguration anlegen
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Jetzt die Pflichtwerte setzen. Die Geheimnisse werden erzeugt, nicht erfunden:
|
||
|
||
```bash
|
||
# Signiert die Sitzungen. Ohne diesen Wert startet die Anwendung nicht.
|
||
openssl rand -base64 32
|
||
|
||
# Ein Passwort für die Datenbank.
|
||
openssl rand -hex 16
|
||
```
|
||
|
||
Unter Windows ohne OpenSSL geht auch:
|
||
|
||
```bash
|
||
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
|
||
```
|
||
|
||
Diese Werte in `.env` eintragen:
|
||
|
||
| Variable | Beispiel | Bedeutung |
|
||
| ------------------- | -------------------------------------------------------------------- | ------------------------------------------------------- |
|
||
| `INSTANZ` | `daheim` | `firma` oder `daheim` – bestimmt, was es überhaupt gibt |
|
||
| `APP_URL` | `http://localhost:3000` | Adresse ohne Schrägstrich am Ende |
|
||
| `AUTH_SECRET` | _(erzeugt)_ | Signatur der Sitzungen |
|
||
| `POSTGRES_PASSWORD` | _(erzeugt)_ | Passwort der Datenbank |
|
||
| `DATABASE_URL` | `postgresql://planer:<Passwort>@localhost:5432/planer?schema=public` | muss dasselbe Passwort enthalten |
|
||
| `WEBAUTHN_RP_ID` | `localhost` | nackte Domain, ohne Schema und Port |
|
||
| `WEBAUTHN_ORIGIN` | `http://localhost:3000` | exakt wie im Browser, mit Port |
|
||
| `ADMIN_EMAIL` | `du@example.de` | erstes Verwaltungskonto |
|
||
| `ADMIN_PASSWORT` | _(mindestens 12 Zeichen)_ | nur nötig, wenn du dich ohne OIDC anmelden willst |
|
||
|
||
> **Sind die Ports 5432 oder 3000 auf deinem Rechner belegt?**
|
||
> Dann `POSTGRES_PORT` beziehungsweise `APP_PORT` in `.env` auf einen freien
|
||
> Wert setzen. `DATABASE_URL`, `APP_URL` und `WEBAUTHN_ORIGIN` müssen denselben
|
||
> Port nennen.
|
||
|
||
**Erwartet:** `.env` liegt im Projektverzeichnis. Sie gehört niemals ins Git —
|
||
`.gitignore` sorgt dafür.
|
||
|
||
## 3. Starten
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Beim ersten Mal dauert der Bau einige Minuten. Der Ablauf ist: Datenbank
|
||
starten, Migrationen einspielen, Anwendung starten.
|
||
|
||
**Erwartet:**
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
zeigt `db` als `healthy` und `app` als `Up`. Der Dienst `migration` taucht
|
||
nicht mehr auf — er hat seine Arbeit getan und sich beendet.
|
||
|
||
## 4. Prüfen, ob alles läuft
|
||
|
||
```bash
|
||
curl http://localhost:3000/api/health
|
||
```
|
||
|
||
**Erwartet:**
|
||
|
||
```json
|
||
{ "status": "ok", "version": "0.1.0", "instanz": "daheim", "datenbank": "ok" }
|
||
```
|
||
|
||
Steht dort `"datenbank": "fehler"`, stimmt `DATABASE_URL` nicht mit
|
||
`POSTGRES_PASSWORD` überein.
|
||
|
||
## 5. Erste Bereiche und das Verwaltungskonto anlegen
|
||
|
||
```bash
|
||
docker compose run --rm migration node node_modules/prisma/build/index.js db seed
|
||
```
|
||
|
||
**Erwartet:** Die Ausgabe nennt die vier angelegten Bereiche (Firma, Gewerbe,
|
||
Privat, Homelab) und bestätigt das Verwaltungskonto.
|
||
|
||
## 6. Anmelden
|
||
|
||
Im Browser <http://localhost:3000> öffnen.
|
||
|
||
**Erwartet:** Die Anmeldeseite. Mit `ADMIN_EMAIL` und `ADMIN_PASSWORT`
|
||
anmelden — danach steht oben „Guten Tag" und darunter die vier Bereiche.
|
||
|
||
> Ist OIDC eingerichtet, erscheint zusätzlich ein Knopf mit dem Namen aus
|
||
> `OIDC_NAME`. Der Rückleit-URI, den du beim Anbieter hinterlegen musst,
|
||
> lautet `<APP_URL>/api/auth/callback/oidc`.
|
||
|
||
## 7. Einen Passkey hinterlegen
|
||
|
||
Auf **Einstellungen** gehen, unter _Passkeys_ einen Namen für das Gerät
|
||
eintragen (etwa „Arbeitsrechner") und auf **Anlegen** klicken. Das Gerät
|
||
fragt nach Fingerabdruck, Gesicht oder PIN.
|
||
|
||
**Erwartet:** Der Passkey steht in der Liste. Ab jetzt genügt zum Anmelden die
|
||
E-Mail-Adresse und **Mit Passkey anmelden**.
|
||
|
||
> Hinterlege am besten zwei Passkeys auf verschiedenen Geräten. Sonst sperrst
|
||
> du dich aus, wenn ein Gerät verlorengeht.
|
||
|
||
## 8. Aufräumen
|
||
|
||
Wenn `ADMIN_PASSWORT` nur zur Einrichtung gedient hat, kannst du es jetzt
|
||
zusammen mit `ADMIN_EMAIL` aus `.env` entfernen. Das Konto bleibt bestehen.
|
||
|
||
## Wie es weitergeht
|
||
|
||
- [Handbuch](handbuch/) – Anleitung für den Alltag
|
||
- [README](../README.md) – alle Umgebungsvariablen, Betrieb, Sicherung
|
||
- [ROADMAP](../ROADMAP.md) – was in den nächsten Meilensteinen kommt
|
||
|
||
## Wenn etwas klemmt
|
||
|
||
| Symptom | Ursache und Abhilfe |
|
||
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `INSTANZ fehlt in .env` beim Start | `INSTANZ` ist leer. Erlaubt sind nur `firma` und `daheim`. |
|
||
| `Die Konfiguration ist unvollständig` | Die Meldung nennt die fehlende Variable. Sie nennt nie den Wert. |
|
||
| `port is already allocated` | Ein anderer Dienst hält den Port. `APP_PORT` oder `POSTGRES_PORT` ändern. |
|
||
| Passkey lässt sich nicht anlegen | `WEBAUTHN_ORIGIN` muss exakt der Adresse im Browser entsprechen, inklusive Port. `WEBAUTHN_RP_ID` ist die nackte Domain, ohne `https://`. |
|
||
| Anmeldung schlägt immer fehl | Bewusst gibt es nur eine Meldung für alle Fälle. Prüfe im Protokoll der Anwendung: `docker compose logs app`. |
|