bricktrack/QUICKSTART.md

Bricktrack – Schnellstart

Von null auf laufende Instanz. Zeitbedarf: etwa 15 Minuten, davon 10 für den ersten Docker-Build.

Voraussetzungen: Ein Linux-Host (z. B. eine LXC oder VM auf Proxmox) mit Docker und dem Compose-Plugin, ein Reverse Proxy mit gültigem TLS-Zertifikat und eine Subdomain, die auf den Proxy zeigt.

Warum HTTPS Pflicht ist: Passkeys (WebAuthn) funktionieren ausschließlich über HTTPS und sind fest an den Hostnamen gebunden. Ohne Zertifikat bleibt nur die Anmeldung per Passwort. Wird die Domain später geändert, sind alle Passkeys ungültig und müssen neu angelegt werden.

---

1. Projekt holen

sudo mkdir -p /opt/bricktrack
sudo chown "$USER" /opt/bricktrack
git clone https://git.wilde-server.de/florian.wilde/bricktrack.git /opt/bricktrack
cd /opt/bricktrack

2. Konfiguration anlegen

cp .env.example .env

Jetzt .env öffnen und zwei Werte setzen:

# Die Adresse, unter der du die App im Browser aufrufst.
BASE_URL=https://bricktrack.example.de

# Signiergeheimnis - hiermit erzeugen:
#   openssl rand -base64 48
BETTER_AUTH_SECRET=<dein-erzeugter-wert>

Alles andere kann so bleiben. DATA_DIR=/data ist der Pfad im Container und wird nicht angefasst.

3. Datenverzeichnis vorbereiten

Der Container läuft aus Sicherheitsgründen nicht als root, sondern als Nutzer mit der UID 1000. Das gemountete Verzeichnis muss ihm gehören:

mkdir -p ./data
sudo chown -R 1000:1000 ./data

Diesen Schritt vergisst man gern – der Container sagt dir dann aber beim Start genau das.

4. Starten

docker compose up -d --build

Der erste Build dauert einige Minuten. Danach:

docker compose ps          # Status "healthy" abwarten
docker compose logs -f app # Log mitlesen, mit Strg+C beenden
curl -s http://127.0.0.1:3000/api/health
# {"status":"ok","time":"..."}

5. Reverse Proxy einrichten (Nginx Proxy Manager)

In NPM unter Hosts → Proxy Hosts → Add Proxy Host:

Reiter „Details"

Feld	Wert
Domain Names	bricktrack.example.de
Scheme	http
Forward Hostname / IP	IP des Docker-Hosts, z. B. 192.168.1.50
Forward Port	3000
Cache Assets	aus (Next.js setzt seine Cache-Header selbst)
Block Common Exploits	an
Websockets Support	an

Reiter „SSL"

Feld	Wert
SSL Certificate	Let's Encrypt anfordern oder vorhandenes wählen
Force SSL	an
HTTP/2 Support	an
HSTS Enabled	an (optional, aber sinnvoll)

Reiter „Advanced" – hier hinein, sonst scheitern große Anleitungs-PDFs am Standardlimit von 1 MB:

# Anleitungs-PDFs koennen mehrere Megabyte gross sein.
client_max_body_size 64m;

# Uploads und PDF-Auslieferung duerfen etwas dauern.
proxy_read_timeout 300;
proxy_send_timeout 300;

# Die App leitet ihre oeffentliche Adresse und die Client-IP hieraus ab.
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host  $host;
proxy_set_header X-Real-IP         $remote_addr;

client_max_body_size muss mindestens so groß sein wie MAX_UPLOAD_MB in deiner .env (Standard 25 MB); 64m gibt Luft.

Läuft NPM im selben Docker-Netz? Dann in docker-compose.yml das Port-Mapping auf - "3000:3000" ändern oder ganz entfernen und beide Container in ein gemeinsames Netzwerk hängen. Als Forward Hostname trägst du dann bricktrack ein (den Container-Namen), Port 3000.

Die Voreinstellung 127.0.0.1:3000:3000 bindet den Port nur an localhost – die App ist dann ausschließlich über den Proxy erreichbar. Sitzt NPM auf einem anderen Host, muss das Mapping auf 3000:3000 geändert und der Zugriff per Firewall beschränkt werden.

6. Ersten Nutzer anlegen

https://bricktrack.example.de aufrufen. Die App leitet direkt auf die Registrierung.

Der erste registrierte Nutzer wird automatisch Administrator. Danach ist die Registrierung geschlossen – weitere Konten entstehen nur über einen Einladungslink (ab Version 0.2.0).

Also: gleich beim ersten Aufruf selbst registrieren, bevor es jemand anderes tut.

7. Passkey hinterlegen

Unter Konto → Passkeys → Passkey hinzufügen. Ab dann meldest du dich per Fingerabdruck, Gesichtserkennung oder Geräte-PIN an. Für jedes Gerät ein eigener Passkey – Handy, Tablet, Laptop.

8. Loslegen

1. Verwaltung → Hersteller: Lego, Playmobil, Cobi … anlegen.
2. Verwaltung → Themen: „City", „Technic", „Novelmore" …
3. Verwaltung → Standorte: „Regal Kinderzimmer", „Kiste Keller 3" …
4. Katalog → Set anlegen: Setnummer, Name, Bild.
5. Auf der Set-Seite „Zur Sammlung hinzufügen", wenn das Set da ist.
6. Katalog → Filter „Fehlt noch": Kachel lange drücken, mehrere auswählen, „Zur Wunschliste hinzufügen".
7. Wunschlisten → Liste öffnen → Link kopieren und verschicken.

Zum Ausprobieren gibt es Beispieldaten:

docker compose exec app node -e "process.exit(0)"   # laeuft der Container?
docker compose exec app sh -c 'echo "Seed nur in der Entwicklung"'

Das Seed-Skript ist bewusst nicht im Produktions-Image. Zum Ausprobieren lokal: pnpm db:seed.

---

Sichern

Alles, was zählt, liegt in einem Verzeichnis:

docker compose stop app
tar czf bricktrack-$(date +%F).tar.gz data .env
docker compose start app

Zurückspielen:

docker compose down
tar xzf bricktrack-2026-09-06.tar.gz
sudo chown -R 1000:1000 ./data
docker compose up -d

Aktualisieren

./update.sh

Das Skript sichert vorher automatisch, baut neu, wartet auf den Healthcheck und rollt bei einem Fehlschlag zurück. Details in der README.

---

Wenn etwas klemmt

Symptom	Ursache und Lösung
FEHLER: In /data darf nicht geschrieben werden	sudo chown -R 1000:1000 ./data
Container startet, aber unhealthy	docker compose logs app – meist eine fehlende Variable in .env
Ungueltige Umgebungsvariablen: BETTER_AUTH_SECRET	Das Geheimnis braucht mindestens 32 Zeichen
Passkey lässt sich nicht anlegen	Kein HTTPS, oder BASE_URL passt nicht zur aufgerufenen Domain
Passkeys funktionieren nach einem Domainwechsel nicht mehr	Erwartet – Passkeys sind an die Domain gebunden, neu anlegen
413 Request Entity Too Large beim PDF-Upload	client_max_body_size im Proxy erhöhen (Schritt 5)
Anmeldung meldet „Zu viele Versuche"	Rate-Limit: fünf Fehlversuche pro Minute, danach kurz warten