Selbst-Hosting on Seurch Dokumentation

Voraussetzungen

Mon, 01 Jan 0001 00:00:00 +0000

Voraussetzungen#

Laufzeitumgebung#

Komponente	Hinweise
Eine Container-Laufzeitumgebung	Docker oder Podman, um das veröffentlichte Image auszuführen.
PostgreSQL	Die Anwendungsdatenbank. Jedes halbwegs aktuelle PostgreSQL (16+) funktioniert.
Ein Brave Search API-Schlüssel	Das Minimum für nützliche Ergebnisse; siehe Suchanbieter. Das kostenlose Kontingent reicht zum Starten.
Ausgehendes HTTPS	Der Server ruft vorgelagerte Anbieter ab; wenn Sie hinter einer Zulassungsliste sind, sehen Sie die Anbieter-Hosts.

Alles andere – Webserver, Bereitstellung statischer Dateien und Kompilierung der Übersetzungskataloge – ist im Image enthalten.

Schnellstart

Mon, 01 Jan 0001 00:00:00 +0000

Schnellstart#

Der schnellste Weg zu einer laufenden Instanz ist das Docker-Image. Sie benötigen eine PostgreSQL-Datenbank und mindestens einen Brave Search API-Schlüssel.

Mit Docker#

docker run -p 8000:8000 \
 -e SECRET_KEY=ihr-langer-zufaelliger-schluessel \
 -e DATABASE_URL=postgres://benutzer:passwort@db-host:5432/seurch \
 -e ALLOWED_HOSTS=search.example.com \
 -e BRAVE_API_KEY=ihr-brave-schluessel \
 -e BRAVE_SUGGEST_API_KEY=ihr-brave-suggest-schluessel \
 -e MARGINALIA_API_KEY=public \
 seurch

Beim Start:

Wendet Datenbank-Migrationen an (kein Vorgang, wenn das Schema aktuell ist).
Stellt die App mit gunicorn (2 Worker) auf Port 8000 bereit.
Stellt eigene statische Dateien über WhiteNoise bereit (komprimiert und gehasht), kein separater Webserver oder CDN erforderlich.
Antwortet auf eine Gesundheitsprüfung unter /up.

Die Übersetzungskataloge und statischen Dateien werden beim Build kompiliert, sodass nichts weiteres gestartet werden muss.

Konfiguration

Mon, 01 Jan 0001 00:00:00 +0000

Konfiguration#

Seurch wird vollständig über Umgebungsvariablen (in der Produktion) oder eine .env-Datei (in der Entwicklung) konfiguriert. Das Repository enthält eine .env.example, die jede Variable dokumentiert; diese Seite ist die Referenz.

Kern#

Variable	Zweck	Hinweise
`SECRET_KEY`	Django-Geheimschlüssel	In der Produktion erforderlich. Lang und zufällig.
`DEBUG`	Debug-Modus	In der Produktion `False` (der Standard) belassen.
`ALLOWED_HOSTS`	Kommagetrennte Hostnamen, die die App bedient	z.B. `search.example.com`.
`DATABASE_URL`	PostgreSQL-Verbindungs-URL	z.B. `postgres://user:pass@host:5432/seurch`.
`LOG_LEVEL`	Protokollierungsausführlichkeit	`DEBUG` / `INFO` / `WARNING` / `ERROR` (Standard `INFO`).

Suchanbieter#

Diese Schlüssel bestimmen, welche Suchmaschinen, Medien-Tabs und Wissenskarten verfügbar sind. Ein Anbieter ohne Schlüssel wird einfach ausgeblendet (nicht als defekt angezeigt). Vollständige Details unter Suchanbieter.

Suchanbieter

Mon, 01 Jan 0001 00:00:00 +0000

Suchanbieter#

Seurch kombiniert Ergebnisse von mehreren unabhängigen Anbietern. Welche Tabs und Karten erscheinen, hängt davon ab, welche Schlüssel Sie setzen. Ein Anbieter ohne Schlüssel wird ausgeblendet; der betroffene Tab oder die Karte erscheint einfach nicht, anstatt einen Fehler anzuzeigen.

Alle vorgelagerten Aufrufe erfolgen serverseitig; Schlüssel werden nie an den Browser weitergegeben.

Diese Seite bietet den Überblick darüber, welcher Schlüssel was aktiviert. Schritt-für-Schritt-Anweisungen zur Anmeldung bei jedem Anbieter finden Sie unter API-Schlüssel erhalten.

API-Schlüssel erhalten

Mon, 01 Jan 0001 00:00:00 +0000

API-Schlüssel erhalten#

Schritt-für-Schritt-Anleitungen zum Erhalten des Schlüssels jedes Anbieters. Keiner ist erforderlich, um Seurch zu starten, aber mindestens eine Web-Suchmaschine (Brave ist am einfachsten) wird für nützliche Ergebnisse benötigt. Jeder Anbieter, den Sie überspringen, blendet seinen Tab oder seine Karte einfach aus; unter Suchanbieter finden Sie, was jeder aktiviert.

Sobald Sie einen Schlüssel haben, setzen Sie die entsprechende Umgebungsvariable (siehe Konfiguration) und starten Sie die App neu.

Alle haben ein kostenloses Kontingent, das für eine persönliche oder kleine Team-Instanz großzügig genug ist; Seurch cached aggressiv und ruft die kostenpflichtigen Karten-APIs nur auf, wenn eine Anfrage tatsächlich übereinstimmt. Die geteilten Schlüssel (public für Marginalia, anonymes Stack Exchange) benötigen überhaupt keine Anmeldung.

Übersetzung

Mon, 01 Jan 0001 00:00:00 +0000

Übersetzung (LibreTranslate)#

Der Übersetzen-Tab wird von LibreTranslate betrieben, einem Open-Source, selbst-hostbaren Maschinenübersetzungsserver. Seurch ruft ihn serverseitig auf; kein Drittanbieter-Übersetzungsdienst ist beteiligt.

Den Tab aktivieren#

Zeigen Sie Seurch mit LIBRETRANSLATE_URL auf eine LibreTranslate-Instanz:

LIBRETRANSLATE_URL=http://libretranslate:5000

Gesetzt: Der Übersetzen-Tab (und seine Einstellung) erscheinen mit den Sprachen, die diese Instanz anbietet.
Nicht gesetzt: Der Übersetzen-Tab und seine Einstellung werden vollständig deaktiviert.

LibreTranslate betreiben#

Der Entwicklungs-Stack startet automatisch ein lokales LibreTranslate (make up startet eines unter http://localhost:5000). Für die Produktion betreiben Sie Ihr eigenes, zum Beispiel:

Benutzer & Zugang

Mon, 01 Jan 0001 00:00:00 +0000

Benutzer & Zugang#

Seurch ist nur mit Anmeldung zugänglich und hat keine öffentliche Registrierung; als Administrator kontrollieren Sie, wer ein Konto hat. Dies hält eine Instanz privat für Ihre Benutzer.

Konten erstellen#

Erstellen Sie Benutzer mit Djangos Standard-Verwaltungsbefehl:

# Docker
docker exec -it <container> python manage.py createsuperuser

# Aus dem Quellcode
make superuser

createsuperuser erstellt ein Admin-Konto; für gewöhnliche Benutzer können Sie diese auf die gleiche Weise erstellen (oder über das Django-Admin, sobald Sie einen Superuser haben). Jedes Konto benötigt einen Benutzernamen und ein Passwort; eine E-Mail ist optional (siehe unten).

API-Schlüssel

Mon, 01 Jan 0001 00:00:00 +0000

API-Schlüssel#

Benutzer greifen auf die öffentliche API mit benutzerspezifischen API-Schlüsseln zu. Benutzer können ihre eigenen Schlüssel in der Web-UI verwalten (Einstellungen → API-Schlüssel), und Sie können sie über die Befehlszeile verwalten.

Wie Schlüssel gespeichert werden#

Ein Schlüssel sieht aus wie seurch_sk_<präfix>.<geheimnis>:

Das Präfix (8 Zeichen) wird im Klartext für die schnelle Suche gespeichert.
Nur ein SHA-256-Hash des Geheimnisses wird gespeichert, nie das Geheimnis selbst.

Daher wird der vollständige Wert eines Schlüssels genau einmal angezeigt, bei der Erstellung, und kann danach nicht wiederhergestellt, nur widerrufen werden.

Wartung

Mon, 01 Jan 0001 00:00:00 +0000

Wartung#

Seurch benötigt wenig laufende Pflege, aber einige Verwaltungsbefehle halten es ordentlich und aktuell. Führen Sie diese nach einem Zeitplan aus (ein Cron-Job, ein systemd-Timer oder die Funktion für geplante Aufgaben Ihres Orchestrators). Führen Sie jeden im Container aus (docker exec <container> python manage.py …) oder via make / uv run aus dem Quellcode.

Geplante Aufgaben#

Befehl	Was er tut	Empfohlener Zeitplan
`clear_expired_cache`	Löscht abgelaufene Suchergebnis-Cache-Zeilen	Täglich
`check_provider_health`	Prüft Anbieter mit einem kostenlosen Gesundheits-Endpunkt, damit `/status` aktuell bleibt, ohne kostenpflichtiges Kontingent zu verbrauchen	Alle ~10 Minuten
`refresh_currency`	Aktualisiert gecachte Wechselkurse und bereinigt den Sofortantwort-Cache	Täglich (optional, aktualisiert sich auch bei Bedarf selbst)

Ein Cron-Beispiel:

Produktionshinweise

Mon, 01 Jan 0001 00:00:00 +0000

Produktionshinweise#

Einige wichtige Punkte, wenn Sie Seurch für echte Benutzer betreiben.

Das Image#

Stellt die App mit gunicorn (2 Worker) auf Port 8000 bereit.
Stellt eigene statische Dateien über WhiteNoise bereit, komprimiert und gehasht, sodass Sie keinen separaten statischen Dateiserver oder CDN benötigen.
Kompiliert Übersetzungskataloge und sammelt statische Dateien zur Build-Zeit.
Führt Datenbank-Migrationen beim Start aus.

Reverse-Proxy und TLS#

Stellen Sie einen TLS-terminierenden Reverse-Proxy davor (Caddy, nginx, Traefik, …) und leiten Sie an Port 8000 weiter. Setzen Sie: