Konfigurace

4 min čtení

Rychlý start

  1. Nainstalujte PgArachne
  2. Nastavte prostředí
  3. Nastavte bezpečnost a autentizaci
  4. Nasaďte za HTTPS proxy

Konfigurace

PgArachne načítá konfiguraci z proměnných prostředí nebo ze souboru.

Poznámka: schema.sql se pokusí vytvořit roli pgarachne_admin a přiřadit ji roli pgarachne. Bez superuser práv se vytvoření přeskočí. V tom případě vytvořte roli a nastavte grant ručně.
Proxy uživatel (DB_USER) musí být členem pgarachne a pgarachne_admin, aby mohl ověřovat a vytvářet API tokeny.
Bezpečnostní poznámka: PgArachne nepracuje s hesly k databázi v konfiguračním souboru. Pro autentizaci spoléhá na standardní mechanismus PostgreSQL souboru .pgpass (nebo systémovou proměnnou PGPASSWORD).
Tip: Pokud běží PgArachne za reverse proxy, nastavte TRUSTED_PROXIES, aby se správně určovala IP klienta a nešlo obejít rate limiting.
Pořadí hledání: Pokud není konfigurační soubor specifikován přes CLI, hledá se v tomto pořadí:
  1. Aktuální složka: ./pgarachne.env (všechny OS)
  2. Uživatelská konfigurace:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Systémová konfigurace: /etc/pgarachne/pgarachne.env (pouze Linux/macOS)

Příklad minimální konfigurace

Pro základní spuštění aplikace postačuje následující nastavení:

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Povinné proměnné: DB_HOST, DB_PORT, DB_USER, JWT_SECRET (minimálně 32 bajtů; vygenerujte pomocí openssl rand -hex 32).

Rychlý validační checklist

  • JWT_SECRET je dlouhý, náhodný a není sdílený mezi prostředími.
  • DB_USER může přepínat jen do očekávaných rolí (zkontrolujte role membership granty).
  • TRUSTED_PROXIES je nastaveno, pokud běžíte za reverse proxy.
  • LOGIN_RATE_LIMIT je zapnut pro veřejně dostupné nasazení.
  • METRICS_LISTEN_ADDR je neveřejný (např. 127.0.0.1:9090).

Kompletní přehled nastavení

ProměnnáPovinnéPopis
Připojení k databázi
DB_HOST✓Adresa PostgreSQL serveru (např. localhost).
DB_PORT✓Port databáze.
DB_USER✓Databázový uživatel, pod kterým se PgArachne připojuje.
DB_SSLMODE○SSL režim PostgreSQL. Výchozí: require. Hodnotu disable nastavte explicitně jen pro lokální vývoj proti PostgreSQL bez TLS.
DB_SSLROOTCERT○Cesta k CA root certifikátu (PEM).
DB_SSLCERT○Cesta ke klientskému certifikátu (PEM).
DB_SSLKEY○Cesta ke klientskému privátnímu klíči (PEM).
HTTP Server
HTTP_PORT○Port pro naslouchání. Výchozí: 8080.
API_PREFIX○První segment URL cesty pro všechny databázové endpointy (/jsonrpc, /sse, /mcp). Výchozí: db, výsledné cesty jako /db/:databaze/jsonrpc. Povoleny jsou pouze písmena, číslice, pomlčky a podtržítka.
PID_FILE○Cesta k PID souboru démona používanému při -start/-stop. Výchozí: cache adresář uživatele (fallback: temp adresář).
ALLOWED_ORIGINS○Nastavení CORS. Čárkou oddělený seznam povolených domén (např. https://mojeaplikace.cz). Výchozí: nenastaveno — cross-origin požadavky z prohlížeče jsou zakázané. Pro povolení libovolného původu nastavte explicitně *.
STATIC_FILES_PATH○Absolutní cesta k servírování statických souborů (Explorer/Frontend).
Bezpečnost (JWT)
JWT_SECRET✓Dlouhý náhodný řetězec používaný k podepisování relačních tokenů. Minimálně 32 bajtů; vygenerujte pomocí openssl rand -hex 32.
JWT_EXPIRY_HOURS○Platnost relace v hodinách. Výchozí: 8.
JWT_ISSUER○Pokud je nastaveno, zapisuje se do claimu iss a musí přesně souhlasit při ověření. Prázdné = kontrola vypnuta.
JWT_AUDIENCE○Pokud je nastaveno, zapisuje se do claimu aud a musí souhlasit při ověření. Prázdné = kontrola vypnuta.
JWT_LEEWAY○Tolerance hodinového posunu pro exp/nbf/iat (např. 30s). Výchozí: 30s.
LOGIN_RATE_LIMIT○Max. počet pokusů o přihlášení v okně. Pro vypnutí nastavte 0. Výchozí: 5
LOGIN_RATE_LIMIT_PER_IP○Max. počet pokusů o přihlášení na IP klienta napříč všemi uživatelskými jmény, takže střídání jmen limit neobejde. Výchozí: 5× LOGIN_RATE_LIMIT. Pro vypnutí nastavte 0.
LOGIN_RATE_WINDOW○Délka časového okna pro omezení. Výchozí: 1m.
Omezení přihlášení je platné pro jednu instanci (uloženo v paměti). Při provozu více instancí je nutný sdílený limiter pro globální vynucení.
TRUSTED_PROXIES○Důvěryhodné proxy IP/CIDR pro zpracování X-Forwarded-For. Čárkou oddělené. Pokud je hodnota prázdná, forwardované hlavičky se ignorují a IP klienta se bere z přímého spojení.
MAX_REQUEST_BYTES○Maximální velikost request body v bajtech. Výchozí: 2097152.
MCP_SQL_ERROR_DETAIL○Zahrnout surovou chybovou zprávu PostgreSQL do chyb MCP nástrojů. Detailní chyby pomáhají LLM agentům se opravit, ale mohou odhalit detaily schématu (názvy tabulek a omezení) autentizovaným volajícím. Výchozí: false.
DIRECT_POOL_LIMIT○Maximální počet různých connection poolů pro přihlašovací údaje Basic Auth. Výchozí: 1000.
METRICS_ENABLED○Povolit dedikovaný endpoint metrik. Výchozí: true.
METRICS_LISTEN_ADDR○Adresa listeneru metrik (host:port). Výchozí: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Maximální počet kanálů na SSE připojení. Výchozí: 8.
SSE_MAX_CLIENTS○Maximální počet současných SSE klientů na databázi. Výchozí: 1000.
SSE_CLIENT_BUFFER○Velikost per‑klientského bufferu SSE (počet zpráv). Výchozí: 64.
SSE_SEND_TIMEOUT○Maximální čekání při odesílání pomalému klientovi. Výchozí: 2s.
SSE_HEARTBEAT○Interval heartbeat zpráv pro SSE. Výchozí: 20s.
SSE_IDLE_TIMEOUT○Timeout neaktivity bez notifikací. Výchozí: 90s.
Logování
LOG_LEVEL○Úroveň detailů: DEBUG, INFO, WARN, ERROR. Výchozí: INFO.
LOG_OUTPUT○Kam zapisovat logy: stdout nebo cesta k souboru.

Povinné   Volitelné

Bezpečnostní chování: požadavky bez validní hlavičky Authorization jsou odmítnuty ještě před navázáním databázového připojení.

Spuštění serveru:

./pgarachne -config .env

Viz také

Související dokumentace

← Instalace JSON-RPC (Hello World) →