planer/docs/SCHNELLSTART.md

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

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

cp .env.example .env

Jetzt die Pflichtwerte setzen. Die Geheimnisse werden erzeugt, nicht erfunden:

# 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:

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

docker compose up -d --build

Beim ersten Mal dauert der Bau einige Minuten. Der Ablauf ist: Datenbank starten, Migrationen einspielen, Anwendung starten.

Erwartet:

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

curl http://localhost:3000/api/health

Erwartet:

{ "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

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 – Anleitung für den Alltag
• README – alle Umgebungsvariablen, Betrieb, Sicherung
• ROADMAP – 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.