Florian WildeandClaude Opus 5
d01c49b5a0
Jede Seite erklärt nicht nur, wo man klickt, sondern warum es so gebaut ist: warum die Schnellerfassung nur ein Feld hat, warum die Inbox kein eigener Zustand ist, warum Ideen getrennt liegen und warum Verworfenes nicht in den Fortschritt zählt. README und Schnellstart auf den Stand von M2 gebracht; der Schnellstart endet jetzt mit der ersten erfassten Aufgabe. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
168 lines
7.1 KiB
Markdown
168 lines
7.1 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. 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`. |
|