3 Min. Lesezeit

Schnellstart

  1. PgArachne installieren
  2. Umgebung konfigurieren
  3. Sicherheit und Auth konfigurieren
  4. Hinter HTTPS-Proxy bereitstellen

Konfiguration

PgArachne lädt die Konfiguration aus Umgebungsvariablen oder einer Datei.

Note: schema.sql versucht, die Rolle pgarachne_admin zu erstellen und an pgarachne zu vergeben. Ohne Superuser-Rechte wird die Erstellung übersprungen. Rolle und Grant ggf. manuell anlegen.
Der Proxy-User (DB_USER) muss Mitglied von pgarachne und pgarachne_admin sein, um API-Token zu prüfen und zu erstellen.
Sicherheitshinweis: PgArachne verarbeitet keine Datenbankpasswörter in der Konfigurationsdatei. Es verlässt sich auf den Standardmechanismus der .pgpass-Datei von PostgreSQL (oder die systemweite Variable PGPASSWORD) für die Authentifizierung.
Tipp: Wenn PgArachne hinter einem Reverse Proxy läuft, setze TRUSTED_PROXIES, damit die Client-IP korrekt ermittelt wird und das Rate Limiting nicht spoofbar ist.
Suchreihenfolge: Wenn keine Konfigurationsdatei über CLI angegeben ist, wird wie folgt gesucht:
  1. Aktuelles Verzeichnis: ./pgarachne.env (Alle Betriebssysteme)
  2. Benutzerkonfiguration:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Systemkonfiguration: /etc/pgarachne/pgarachne.env (Nur Linux/macOS)

Minimales Konfigurationsbeispiel

Das ist alles, was Sie zum Einstieg benötigen:

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
JWT_SECRET=change_me_to_something_secure

Schnelle Validierungs-Checkliste

  • JWT_SECRET ist lang, zufällig und wird nicht zwischen Umgebungen geteilt.
  • DB_USER kann nur auf erwartete Rollen wechseln (Role-Membership-Grants prüfen).
  • TRUSTED_PROXIES ist gesetzt, wenn PgArachne hinter einem Reverse Proxy läuft.
  • LOGIN_RATE_LIMIT ist für öffentlich erreichbare Deployments aktiviert.
  • METRICS_LISTEN_ADDR ist nicht öffentlich (z. B. 127.0.0.1:9090).

Konfigurationsreferenz

VariableErforderlichBeschreibung
Datenbank-Verbindung
DB_HOST✓PostgreSQL-Serveradresse (z. B. localhost).
DB_PORT✓Datenbankport.
DB_USER✓Der Datenbankbenutzer, mit dem sich PgArachne verbindet.
DB_SSLMODE○PostgreSQL-SSL-Modus. Standard: disable.
DB_SSLROOTCERT○Pfad zum CA-Root-Zertifikat (PEM).
DB_SSLCERT○Pfad zum Client-Zertifikat (PEM).
DB_SSLKEY○Pfad zum privaten Client-Schlüssel (PEM).
HTTP-Server
HTTP_PORT○Port, auf dem gelauscht wird. Standard: 8080.
API_PREFIX○Erstes URL-Pfadsegment für alle Datenbank-Endpunkte (/jsonrpc, /sse, /mcp). Standard: db, ergibt Routen wie /db/:datenbank/jsonrpc. Auf api setzen für Legacy-Pfade. Nur Buchstaben, Ziffern, Bindestriche und Unterstriche erlaubt.
PID_FILE○Pfad zur Daemon-PID-Datei für -start/-stop. Standard: User-Cache-Verzeichnis (Fallback: Temp-Verzeichnis).
ALLOWED_ORIGINS○CORS-Einstellungen. Kommagetrennte Liste zulässiger Domains (z. B. https://meineapp.de). Standard: *.
STATIC_FILES_PATH○Absoluter Pfad zum Bereitstellen statischer Dateien (Explorer/Frontend).
Sicherheit (JWT)
JWT_SECRET✓Eine lange, zufällige Zeichenfolge zum Signieren von Sitzungstoken.
JWT_EXPIRY_HOURS○Gültigkeit der Sitzung in Stunden. Standard: 8.
LOGIN_RATE_LIMIT○Maximale Login-Versuche pro Zeitfenster. Standard: 5. 0 deaktiviert.
LOGIN_RATE_WINDOW○Dauer des Zeitfensters. Standard: 1m.
Login-Rate-Limit ist pro Instanz (in-memory). Bei mehreren Instanzen ist ein geteilter Limiter nötig.
TRUSTED_PROXIES○Vertrauenswürdige Proxy-IPs/CIDRs für X-Forwarded-For. Kommagetrennt. Wenn leer, werden Forwarded-Header ignoriert und die Client-IP aus der direkten Verbindung übernommen.
MAX_REQUEST_BYTES○Maximale Request-Body-Größe in Bytes. Standard: 2097152.
METRICS_ENABLED○Dedizierten Metrics-Endpunkt aktivieren. Standard: true.
METRICS_LISTEN_ADDR○Adresse des Metrics-Listeners (host:port). Standard: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Maximale Anzahl von Kanälen pro SSE-Verbindung. Standard: 8.
SSE_MAX_CLIENTS○Maximale Anzahl gleichzeitiger SSE-Clients pro Datenbank. Standard: 1000.
SSE_CLIENT_BUFFER○SSE-Buffer pro Client (Anzahl Nachrichten). Standard: 64.
SSE_SEND_TIMEOUT○Maximale Wartezeit beim Senden an langsame Clients. Standard: 2s.
SSE_HEARTBEAT○Heartbeat-Intervall für SSE-Verbindungen. Standard: 20s.
SSE_IDLE_TIMEOUT○Timeout bei Inaktivität ohne Benachrichtigungen. Standard: 90s.
Logging
LOG_LEVEL○Ausführlichkeit: DEBUG, INFO, WARN, ERROR. Standard: INFO.
LOG_OUTPUT○Wohin Logs geschrieben werden: stdout oder Dateipfad.

Erforderlich   Optional

Sicherheitsverhalten: Requests ohne gültigen Authorization-Header werden abgelehnt, bevor eine Datenbankverbindung geöffnet wird.

Starten Sie den Server:

./pgarachne -config .env

Siehe auch

Verwandte Doku

← Installation Hello World Beispiel →