# 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. Die erste Aufgabe erfassen

Auf der Startseite steht oben ein Feld **Was ist zu tun?**. Titel eintippen,
Enter.

**Erwartet:** Eine kurze Bestätigung, und der Zähler neben **Inbox** im Menü
springt auf 1. Dort kannst du die Aufgabe einem Bereich zuordnen.

Mehr dazu: [Aufgaben erfassen und wiederfinden](handbuch/aufgaben.md).

## 9. 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, insbesondere
  [Aufgaben](handbuch/aufgaben.md), [Ideen](handbuch/ideen.md) und
  [Projekte](handbuch/projekte.md)
- [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`.                             |