3 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.

Note: 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=change_me_to_something_secure

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í: disable.
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. Nastavte na api pro zachování starých cest. 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í: *.
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ů.
JWT_EXPIRY_HOURS○Platnost relace v hodinách. Výchozí: 8.
LOGIN_RATE_LIMIT○Max. počet pokusů o přihlášení v okně. Pro vypnutí nastavte 0. Výchozí: 5
LOGIN_RATE_WINDOW○Délka časového okna pro limit. Výchozí: 1m.
Omezení přihlášení je per instance (v paměti). Ve více instancích je potřeba 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.
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) →