Installation¶

Voraussetzungen¶

Für Entwicklung und Build wird Go 1.27.1 oder eine kompatible neuere Version benötigt. Für JavaScript-Syntaxchecks kommt zusätzlich node dazu. Die optionalen Playwright-Smoke-Tests brauchen npm und einen Playwright-kompatiblen Browser; lokal ist standardmäßig der Chrome-Channel konfiguriert.

Für den Raspberry Pi 5 mit 64-Bit-Linux ist das offizielle Go-Paket go1.27.1.linux-arm64.tar.gz verfügbar. Der BearStack-Produktionsbuild für Linux ARM64 wird ohne CGO geprüft.

Vorschau, OCR und Medienfunktionen nutzen externe Werkzeuge nur dort, wo sie gebraucht werden:

• poppler-utils für PDF-Vorschau, PDF-Merge bei EML-Archiven und OCR-Vorbereitung
• chromium für gerenderte EML-Mailabbildungen
• LibreOffice, konkret soffice, für Office-Vorschau und Volltextextraktion
• tesseract mit Sprachpaketen für OCR
• ffmpeg für Video- und Fallback-Thumbnails
• optional vipsthumbnail für schnelle Bild-Thumbnails

Schnellstart¶

BEARSTACK_AUTH_USER=admin \
BEARSTACK_AUTH_PASSWORD=change-me \
go run ./cmd/bearstack

Standardwerte:

Ohne aktives Config- oder SQLite-Konto ist Auth auf Loopback-Adressen wie 127.0.0.1:8080 für die Ersteinrichtung deaktiviert. Listener auf nicht-lokalen Interfaces wie 0.0.0.0:8080 oder :8080 starten nur mit mindestens einem aktiven Konto; dieses darf vollständig aus der SQLite-Datenbank stammen. Ohne Auth werden nur Anfragen von Loopback-Gegenstellen mit localhost oder einer Loopback-IP als HTTP-Host akzeptiert; fremde Hostnamen werden zum Schutz vor DNS-Rebinding mit 403 abgewiesen. Vor dem Zugriff über einen eigenen Hostnamen oder Reverse Proxy muss ein Konto eingerichtet werden.

Lokale Entwicklung¶

Der lokale Start nutzt standardmäßig das Repo-nahe Verzeichnis data/:

go run ./cmd/bearstack

Mit getrenntem Entwicklungsdatenverzeichnis:

BEARSTACK_DATA_DIR=/tmp/bearstack-dev go run ./cmd/bearstack

Eine .env-Datei im Arbeitsverzeichnis wird automatisch gelesen. Zusätzlich kann BEARSTACK_ENV_FILE auf eine weitere Env-Datei zeigen. Bereits gesetzte Prozess-Umgebungsvariablen haben Vorrang vor Werten aus Env-Dateien; Werte aus .env haben für denselben Key Vorrang vor BEARSTACK_ENV_FILE.

Tests¶

Go-Tests und Browser-Syntaxchecks laufen über Make:

make test

Einzeln:

go test ./...
make test-go
make test-js
make test-playwright

make test-go führt go test ./... aus. make test-js nutzt scripts/check-js.sh und ruft node --check für alle Browser-Skripte unter internal/server/static/*.js auf. make test-playwright lädt den Test-Runner bei Bedarf über npm exec, erzeugt temporäre Daten, startet BearStack lokal mit eigener Testkonfiguration und prüft Dokumenten-Upload sowie Foto-Galerie.

Die Make-Variablen GO, NODE und NPM können überschrieben werden, zum Beispiel:

NODE=/opt/node/bin/node make test-js

Falls kein lokaler Chrome-Channel verfügbar ist, kann Playwright wie üblich einen Browser installieren:

npx playwright install chromium
PLAYWRIGHT_BROWSER_CHANNEL=chromium make test-playwright

Build¶

Lokal über Make:

make build

Direkt:

go build -trimpath -ldflags="-s -w" -o bearstack ./cmd/bearstack

Cross-Build für Raspberry Pi OS 64-bit:

GOOS=linux GOARCH=arm64 go build -trimpath -ldflags="-s -w" -o bearstack ./cmd/bearstack

Docker und Compose¶

Lokale Python-Umgebungen (.venv, .venv-faces), .cache sowie die Website-Verzeichnisse _site und _site-src werden nicht in den Docker-Buildkontext übernommen.

Image lokal bauen:

docker build -t bearstack:local .

Container starten:

docker run --rm \
  -p 8080:8080 \
  -v bearstack-data:/var/lib/bearstack \
  -e BEARSTACK_AUTH_USER=admin \
  -e BEARSTACK_AUTH_PASSWORD='change-me' \
  bearstack:local

Mit Compose:

BEARSTACK_AUTH_PASSWORD='change-me' docker compose up -d --build

Alternativ mit Passwort-Hash:

BEARSTACK_AUTH_PASSWORD_HASH='$2a$10$...' docker compose up -d --build

Der Container lauscht intern auf 0.0.0.0:8080 und speichert Daten unter /var/lib/bearstack. Deshalb muss Auth im Container gesetzt sein. compose.yaml nutzt standardmäßig admin als Benutzer, reicht BEARSTACK_AUTH_PASSWORD und BEARSTACK_AUTH_PASSWORD_HASH durch und veröffentlicht den Host-Port über BEARSTACK_PORT oder sonst 8080.

Das Runtime-Image basiert auf debian:trixie-slim, die Build-Stage auf golang:1.27.1-trixie. Das Beispiel-Image enthält chromium, ffmpeg, libreoffice-writer, poppler-utils, tesseract-ocr, tesseract-ocr-deu und tesseract-ocr-eng, damit EML-Archive, Foto-/Video-Vorschaubilder, PDF-/Office-Vorschauen, Text-/Office-Volltextextraktion und OCR im Container funktionieren. bubblewrap ist für die optional aktivierbare Konvertersandbox enthalten. Bei aktiviertem Fotomodul muss ein Host-Fotoverzeichnis read-only nach /srv/photos gemountet werden.

Alle Docker-relevanten Umgebungsvariablen:

Konfigurationspriorität im Container: Defaults, dann BEARSTACK_CONFIG, danach Env-Dateien und zuletzt bereits gesetzte Prozess-Umgebungsvariablen aus docker run -e oder compose.yaml. Eine Compose-.env im Projektverzeichnis dient zunächst nur der Variablenersetzung durch Docker Compose; BearStack selbst sieht sie erst, wenn sie in den Container gelangt oder Werte daraus als environment gesetzt werden.

Eine detaillierte Anleitung für Synology DSM mit Container Manager steht in deploy-synology.md.

Multi-Arch-Image für eine Registry bauen und veröffentlichen:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/<owner>/bearstack:<tag> \
  --push .

Auth¶

Für den Betrieb wird Basic Auth mit bcrypt-Hash empfohlen:

sudo apt install -y apache2-utils
htpasswd -bnBC 10 bearstack 'mein-passwort' | cut -d: -f2

Den Hash in JSON direkt eintragen oder in Shell-/Env-Dateien wegen der $-Zeichen quoten:

BEARSTACK_AUTH_PASSWORD_HASH='$2a$10$...'

Wenn password_hash gesetzt ist, hat er Vorrang vor password. Nach erfolgreichem Basic-Auth-Login setzt BearStack ein signiertes HttpOnly-Session-Cookie für 12 Stunden. Mit der Login-Checkbox „Eingeloggt bleiben“ wird die Session auf 30 Tage verlängert. Der Signierschlüssel liegt im Datenverzeichnis, sodass unveränderte Konten nach einem Neustart angemeldet bleiben. Beim Upgrade auf 0.22.0 ist wegen des neuen Sessionformats einmalig eine erneute Anmeldung nötig.

Für einen einzelnen Benutzer reichen BEARSTACK_AUTH_USER und BEARSTACK_AUTH_PASSWORD_HASH; dieser Benutzer bekommt die Rolle admin. Mehrere Benutzer werden in der JSON-Konfiguration über auth.credentials definiert. Sobald diese Liste gesetzt ist, werden auth.username, auth.password und auth.password_hash ignoriert:

"auth": {
  "realm": "BearStack",
  "credentials": [
    {"username": "admin", "password_hash": "$2a$10$...", "role": "admin"},
    {"username": "docs", "password_hash": "$2a$10$...", "role": "documents_read"},
    {"username": "photos", "password_hash": "$2a$10$...", "role": "photos_read"}
  ]
}

Rollen und Einzelrechte sind capability-basiert. Verfügbare Rollen sind admin, documents_read, documents_editor, documents_manager, photos_read, photos_editor, photos_manager und api_uploader. Statt oder zusätzlich zu role können permissions gesetzt werden, zum Beispiel documents.read, documents.webdav.read, documents.upload, documents.edit, documents.delete, documents.structure, photos.read, photos.edit, photos.manage, system.manage, system.users.manage oder system.audit.

Zusätzliche Konten lassen sich unter Einstellungen → Benutzer anlegen. Sie werden mit bcrypt-Hash in bearstack.db gespeichert. JSON-/Env-Konten bleiben parallel aktiv, erscheinen dort aber schreibgeschützt; gleiche Benutzernamen in beiden Quellen verhindern den Start. Sobald ein aktiver SQLite-Admin existiert, kann BearStack nach Entfernung der Config-Zugangsdaten auch auf einem nicht-lokalen Listener ausschließlich mit den Datenbankkonten starten. Für Backups deshalb das gesamte Datenverzeichnis sowie weiterhin verwendete Konfigurationsdateien sichern.

Die ausführliche Rollen- und Rechteübersicht steht unter Benutzer und Rechte.

BearStack startet ohne aktives Konto nur auf Loopback-Adressen. Bei BEARSTACK_ADDR=0.0.0.0:8080, :8080 oder einem anderen nicht-lokalen Host muss mindestens ein aktives Config- oder SQLite-Konto vorhanden sein. Auch bei einem Reverse Proxy vor 127.0.0.1:8080 sollte Auth aktiv bleiben, wenn der Proxy keine eigene Zugriffskontrolle übernimmt.

TLS¶

Für produktiven Betrieb ist meist am einfachsten: BearStack nur auf 127.0.0.1:8080 lauschen lassen und TLS in nginx oder Caddy terminieren.

Direktes HTTPS in BearStack ist möglich:

BEARSTACK_TLS_ENABLED=1 go run ./cmd/bearstack

Mit auto_cert=true erzeugt BearStack ein lokales Self-Signed-Zertifikat unter data/tls/. Browser melden dieses Zertifikat als nicht vertrauenswürdig. Für echte Zertifikate tls.cert_file und tls.key_file bzw. BEARSTACK_TLS_CERT_FILE und BEARSTACK_TLS_KEY_FILE setzen.

Ab 0.42.1 ersetzt die automatische Erzeugung Zertifikat und Schlüssel jeweils atomar über temporäre Dateien. Private Schlüssel erhalten 0600, auch wenn eine vorhandene Datei offenere Rechte hatte. Vorhandene Symlink-Ziele werden dabei nicht überschrieben. Explizit konfigurierte Zertifikate und Schlüssel werden weiterhin nur gelesen.

Wenn TLS aktiv ist, akzeptiert BearStack auf demselben addr sowohl HTTPS als auch plain HTTP. HTTP-Anfragen auf diesem Port werden permanent auf https:// weitergeleitet.

systemd¶

Eine Beispiel-Unit liegt in deploy/bearstack.service und nutzt eine JSON-Konfiguration:

sudo install -o root -g root -m 0755 bearstack /usr/local/bin/bearstack
sudo install -o root -g root -m 0644 deploy/bearstack.service /etc/systemd/system/bearstack.service
sudo systemctl daemon-reload
sudo systemctl enable --now bearstack
systemctl status bearstack
journalctl -u bearstack -n 100 --no-pager

Die Pfade in ReadWritePaths und RequiresMountsFor müssen zur eigenen Konfiguration passen. Eine vollständige Raspberry-Pi-Installation ist in deploy-raspberrypi.md beschrieben.

Backup und Restore¶

Bei eingerichtetem Fotomodul gehört außerdem data_dir/transfers/ vollständig ins Backup: transfers.db, gegebenenfalls transfers.db-wal/transfers.db-shm sowie credentials.key. Die Datenbank enthält Verbindungen, feste Upload-Dateilisten und Aufträge; der Schlüssel entschlüsselt ausschließlich die getrennt gespeicherten Zugangsdaten. Ohne zugehörigen Schlüssel startet das Modul mit bestehender Datenbank nicht. Datenbank und Schlüssel gemeinsam, vertraulich und mit restriktiven Dateirechten sichern und wiederherstellen. Nach Wiederherstellung können bestätigte Aufträge weiterlaufen; gegebenenfalls vor dem Start die Verbindung in einer isolierten Umgebung prüfen. Die Speicherbrücke verändert keine Originalfotos.

Sicherste Backup-Variante: Dienst kurz stoppen und Datenverzeichnis plus Konfiguration sichern.

sudo mkdir -p /var/backups/bearstack
sudo systemctl stop bearstack
sudo tar -czf "/var/backups/bearstack/bearstack-$(date +%Y%m%d-%H%M%S).tgz" \
  /var/lib/bearstack \
  /etc/bearstack/bearstack.json
sudo systemctl start bearstack

Wenn storage_dir außerhalb von data_dir liegt, diesen Pfad ebenfalls sichern. Bei SQLite im WAL-Modus gehören bearstack.db, bearstack.db-wal und bearstack.db-shm zusammen; das Sichern des ganzen Datenverzeichnisses vermeidet unvollständige Backups.

Restore:

sudo systemctl stop bearstack
sudo mv /var/lib/bearstack "/var/lib/bearstack.before-restore-$(date +%Y%m%d-%H%M%S)"
sudo tar -C / -xzf /var/backups/bearstack/<backup-datei>.tgz
sudo chown -R bearstack:bearstack /var/lib/bearstack
sudo chown root:bearstack /etc/bearstack /etc/bearstack/bearstack.json
sudo chmod 640 /etc/bearstack/bearstack.json
sudo systemctl start bearstack
journalctl -u bearstack -n 100 --no-pager

Bei getrenntem Dokumentenspeicher auch diesen vor dem Restore verschieben und nach dem Entpacken die Rechte setzen.

Update¶

Vor Updates ein Datenbackup erstellen. Für systemd-Installationen liegt ein Update-Skript im Repo:

cd /opt/bearstack-src/BearStack
./update.sh

update.sh aktualisiert den aktuellen Branch mit git fetch --all --tags und git pull --ff-only, führt go test ./... aus und baut ein temporäres Binary. Danach wartet es auf systemctl stop und prüft ActiveState=inactive, Result=success und MainPID=0. Bei einem Stop-Fehler, Timeout oder verbliebenen Hauptprozess bricht das Update vor der Installation ab. Nur nach erfolgreichem Stopp wird das Binary installiert und der Dienst gestartet. Den Dienststatus und Smoke-Test anschließend prüfen; automatisches Backup und Rollback sind nicht enthalten.

BearStack beendet bei SIGTERM und SIGINT zunächst die Annahme neuer Hintergrundjobs und signalisiert laufenden Workern den Abbruch. HTTP-Anfragen und Hintergrundjobs einschließlich manuell gestarteter Foto- und Gesichtsläufe haben zusammen bis zu 60 Sekunden zum Abschluss. Erst danach schließen die Datenbanken; ein überschrittenes Zeitlimit führt zu einem Fehlerstatus. Die systemd-Vorlage verwendet TimeoutStopSec=75s. Bestehende eigene Units sollten mindestens diesen Wert erhalten; anschließend sudo systemctl daemon-reload ausführen.

Variablen für das Skript:

Ohne Auth reicht für den manuellen Smoke-Test:

curl -fsS http://127.0.0.1:8080/healthz

Mit Auth:

curl -fsS -u admin:mein-passwort http://127.0.0.1:8080/healthz

Manuell entspricht das im Kern:

git fetch --all --tags
git pull --ff-only
make test
go build -trimpath -ldflags="-s -w" -o bearstack ./cmd/bearstack
sudo systemctl stop bearstack
sudo install -o root -g root -m 0755 bearstack /usr/local/bin/bearstack
sudo systemctl start bearstack
curl -fsS -u admin:mein-passwort http://127.0.0.1:8080/healthz

Typische Fehler¶

• 401 Unauthorized: Auth ist aktiv; mit Basic-Auth-Daten anmelden.
• Start bricht mit at least one active authentication account is required when addr listens on non-loopback interfaces ab: Ein aktives Config-/SQLite-Konto bereitstellen oder BEARSTACK_ADDR auf 127.0.0.1:8080/localhost:8080 beschränken.
• Das Log meldet auth_enabled=false: Es gibt weder ein aktives Config- noch ein aktives SQLite-Konto. Dieser Zustand ist nur auf Loopback zur Ersteinrichtung zulässig.
• open config file oder decode config file: BEARSTACK_CONFIG-Pfad und JSON-Syntax prüfen.
• permission denied bei Datenbank oder Dokumenten: Besitzer/Rechte und ReadWritePaths der Unit prüfen.
• address already in use: Port mit sudo ss -ltnp | grep ':8080' prüfen.
• Upload scheitert mit 413: max_upload_bytes und client_max_body_size im Reverse Proxy angleichen.
• Ein frischer Docker-Container startet auf einem nicht-lokalen Listener wegen fehlender Auth nicht: ein Config-Konto bereitstellen oder zuerst auf Loopback ein SQLite-Admin-Konto anlegen; bestehende DB-Konten im Daten-Volume werden ebenfalls akzeptiert.
• make test-js bricht mit node is required... ab: Node installieren oder NODE=/pfad/zu/node make test-js verwenden.
• make test-playwright scheitert beim Abruf des Test-Runners: npm-Zugang, Netzwerk oder Proxy prüfen und mit lokalem Cache erneut starten.
• make test-playwright findet keinen Browser: Chrome installieren oder npx playwright install chromium ausführen und mit PLAYWRIGHT_BROWSER_CHANNEL=chromium make test-playwright starten.
• go test oder go build meldet Schreibfehler im Go-Build-Cache: GOCACHE auf ein beschreibbares Verzeichnis setzen, zum Beispiel GOCACHE=/tmp/go-build-cache go test ./....
• update.sh startet den Dienst, aber Status oder manueller Smoke-Test schlagen fehl: systemctl status bearstack und journalctl -u bearstack -n 100 --no-pager prüfen; bei aktiver Auth den Smoke-Test mit curl -u ausführen.
• Vorschaubilder für PDFs fehlen: poppler-utils installieren, besonders pdftoppm.
• Text-/Office-Vorschau oder Volltextextraktion für TXT, Markdown, RTF, DOC, DOCX oder Pages fehlt: LibreOffice installieren und command -v soffice prüfen.
• Foto-/Video-Vorschaubilder fehlen: ffmpeg installieren; für Bild-Thumbnails kann optional vipsthumbnail genutzt werden.
• OCR scheitert: tesseract-ocr, Sprachpakete und pdfinfo/pdftoppm prüfen.
• Fotomodul fehlt in der Navigation: BEARSTACK_PHOTOS_ENABLED=true setzen und Dienst neu starten.

Konverter isolieren¶

Ab BearStack 1.11.0 laufen Chromium, LibreOffice, Poppler, Tesseract und die externen Foto-Thumbnail-Werkzeuge über dieselbe begrenzte Prozessausführung. Diagnoseausgaben behalten höchstens 4 KiB plus Kürzungshinweis. OCR-Ausgaben sind auf 10 MiB pro Prozess begrenzt; größere Ergebnisse führen zu einem Fehler und werden nicht als vollständiger Text gespeichert. Serverpasswörter, Tokens, Proxy-Zugangsdaten und persönliche Browser-/Office-Profile werden nicht vererbt. Jeder Prozess erhält ein privates temporäres Home. Unter Linux beendet ein Abbruch auch die Prozessgruppe; geerbte Ausgabepipes haben eine begrenzte Wartezeit.

Für zusätzliche Dateisystem- und Netzwerkisolation kann unter Linux BEARSTACK_CONVERTER_SANDBOX=bubblewrap gesetzt werden. Dafür muss bwrap installiert sein und der Dienst Benutzer-, Mount-, Prozess- und Netzwerk-Namespaces anlegen dürfen. Der Konverter sieht nur benötigte Systemdateien, ausdrücklich freigegebene Eingaben und Ausgabe-/Profilverzeichnisse. Eingaben werden read-only gebunden; /tmp, /proc und das Netzwerk sind privat. Andere Dokumente, die Serverkonfiguration und das Netzwerk des Servers sind nicht erreichbar. Auch Chromium mit --no-sandbox läuft dadurch in einer äußeren Prozesssandbox.

Die Einstellung ist optional; ohne Wert beziehungsweise mit off bleibt die bisherige Konverterverfügbarkeit erhalten. Ein unbekannter Wert oder ein Fehler beim Aufbau der aktivierten Sandbox bricht die Konvertierung ab. Es gibt keinen automatischen ungeschützten Wiederholungsversuch. Für native Installationen kann ein systemd-Drop-in Environment=BEARSTACK_CONVERTER_SANDBOX=bubblewrap setzen. Snap-Konverter sind dafür ungeeignet; native Distributionpakete verwenden.

Compose begrenzt den Hauptdienst auf 256 Prozesse und standardmäßig 2 GiB RAM (BEARSTACK_MEMORY_LIMIT), entfernt Linux-Capabilities, verbietet neue Privilegien und verwendet ein schreibgeschütztes Root-Dateisystem. Schreibbar bleiben das Daten-Volume und /tmp als auf 1 GiB begrenztes tmpfs. Die systemd-Vorlage begrenzt Tasks und schützt zusätzliche Kernel-/Gerätebereiche. Die vollständige Bubblewrap-Sandbox bleibt in Compose standardmäßig aus, da Container-Runtimes verschachtelte Benutzer-Namespaces unterschiedlich einschränken. Nur auf einer dafür geeigneten Laufzeit aktivieren; keine privilegierten Container oder pauschal deaktivierten Seccomp-/AppArmor-Profile dafür verwenden.