Configurazione

4 min di lettura

Avvio rapido

  1. Installa PgArachne
  2. Configura l’ambiente
  3. Configura sicurezza e auth
  4. Distribuisci dietro proxy HTTPS

Configurazione

PgArachne carica la configurazione dalle variabili d’ambiente o da un file.

Nota: schema.sql prova a creare il ruolo pgarachne_admin e a concederlo a pgarachne. Senza privilegi di superuser, la creazione viene saltata. Crea ruolo e grant manualmente se necessario.
L’utente proxy (DB_USER) deve essere membro di pgarachne e pgarachne_admin per verificare e creare token API.
Nota di Sicurezza: PgArachne non gestisce le password del database nel file di configurazione. Si affida al meccanismo standard del file .pgpass di PostgreSQL (o alla variabile di sistema PGPASSWORD) per l’autenticazione.
Suggerimento: Se PgArachne è dietro un reverse proxy, imposta TRUSTED_PROXIES per risolvere correttamente l’IP client ed evitare spoofing del rate limit.
Ordine di Ricerca: Se nessun file di configurazione è specificato via CLI, cerca in:
  1. Directory corrente: ./pgarachne.env (Tutti i SO)
  2. Configurazione utente:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Configurazione di sistema: /etc/pgarachne/pgarachne.env (Solo Linux/macOS)

Esempio di Configurazione Minima

Questo è tutto ciò di cui hai bisogno per iniziare:

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

Variabili obbligatorie: DB_HOST, DB_PORT, DB_USER, JWT_SECRET (minimo 32 byte; generalo con openssl rand -hex 32).

Checklist di Validazione Rapida

  • JWT_SECRET è lungo, casuale e non riutilizzato tra ambienti diversi.
  • DB_USER può passare solo ai ruoli previsti (verifica i grant di appartenenza ai ruoli).
  • TRUSTED_PROXIES è impostato quando si esegue dietro un reverse proxy.
  • LOGIN_RATE_LIMIT è abilitato per i deployment esposti su internet.
  • METRICS_LISTEN_ADDR è privato (per esempio 127.0.0.1:9090).

Riferimento configurazione

VariabileRichiestoDescrizione
Connessione Database
DB_HOST✓Indirizzo del server PostgreSQL (es. localhost).
DB_PORT✓Porta del database.
DB_USER✓L’utente del database con cui PgArachne si connette.
DB_SSLMODE○Modalità SSL di PostgreSQL. Predefinito: require. Imposta disable esplicitamente solo per lo sviluppo locale contro un PostgreSQL senza TLS.
DB_SSLROOTCERT○Percorso del certificato root CA (PEM).
DB_SSLCERT○Percorso del certificato client (PEM).
DB_SSLKEY○Percorso della chiave privata client (PEM).
Server HTTP
HTTP_PORT○Porta su cui ascoltare. Default: 8080.
API_PREFIX○Primo segmento del percorso URL per tutti gli endpoint del database (/jsonrpc, /sse, /mcp). Predefinito: db, con percorsi come /db/:database/jsonrpc. Sono consentiti solo lettere, cifre, trattini e underscore.
PID_FILE○Percorso del file PID del demone usato da -start/-stop. Predefinito: cache utente (fallback: directory temporanea).
ALLOWED_ORIGINS○Impostazioni CORS. Elenco separato da virgole dei domini consentiti (es. https://miapp.com). Default: non impostato — le richieste cross-origin dal browser sono disabilitate. Imposta * esplicitamente per consentire qualsiasi origine.
STATIC_FILES_PATH○Percorso assoluto per servire file statici (Explorer/Frontend).
Sicurezza (JWT)
JWT_SECRET✓Una stringa lunga e casuale usata per firmare i token di sessione. Minimo 32 byte; generalo con openssl rand -hex 32.
JWT_EXPIRY_HOURS○Validità della sessione in ore. Default: 8.
JWT_ISSUER○Se impostato, viene scritto nel claim iss e deve corrispondere esattamente in fase di validazione. Vuoto = nessun controllo.
JWT_AUDIENCE○Se impostato, viene scritto nel claim aud e deve corrispondere in fase di validazione. Vuoto = nessun controllo.
JWT_LEEWAY○Tolleranza dell’orologio per exp/nbf/iat (es. 30s). Predefinito: 30s.
LOGIN_RATE_LIMIT○Numero massimo di tentativi di login per finestra. Predefinito: 5. 0 disabilita.
LOGIN_RATE_LIMIT_PER_IP○Numero massimo di tentativi di login per IP client su tutti i nomi utente, così alternare i nomi non aggira il limite. Predefinito: 5× LOGIN_RATE_LIMIT. 0 disabilita.
LOGIN_RATE_WINDOW○Durata della finestra di rate limit. Predefinito: 1m.
Il rate limit del login è per istanza (in memoria). In multi-istanza serve un limiter condiviso.
TRUSTED_PROXIES○Proxy fidati (IP/CIDR) per X-Forwarded-For. Separati da virgole. Se vuoto, gli header forwarded vengono ignorati e l’IP client viene preso dalla connessione diretta.
MAX_REQUEST_BYTES○Dimensione massima del body in byte. Predefinito: 2097152.
MCP_SQL_ERROR_DETAIL○Includi il messaggio di errore grezzo di PostgreSQL negli errori degli strumenti MCP. Gli errori dettagliati aiutano gli agenti LLM ad autocorreggersi, ma possono esporre dettagli dello schema (nomi di tabelle e vincoli) ai chiamanti autenticati. Predefinito: false.
DIRECT_POOL_LIMIT○Numero massimo di pool di connessione distinti per le credenziali Basic Auth. Predefinito: 1000.
METRICS_ENABLED○Abilita l’endpoint dedicato alle metriche. Predefinito: true.
METRICS_LISTEN_ADDR○Indirizzo del listener metriche (host:port). Predefinito: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Numero massimo di canali per connessione SSE. Predefinito: 8.
SSE_MAX_CLIENTS○Numero massimo di client SSE simultanei per database. Predefinito: 1000.
SSE_CLIENT_BUFFER○Buffer SSE per client (numero di messaggi). Predefinito: 64.
SSE_SEND_TIMEOUT○Tempo massimo di attesa per inviare a un client lento. Predefinito: 2s.
SSE_HEARTBEAT○Intervallo heartbeat per SSE. Predefinito: 20s.
SSE_IDLE_TIMEOUT○Timeout di inattività senza notifiche. Predefinito: 90s.
Logging
LOG_LEVEL○Verbosità: DEBUG, INFO, WARN, ERROR. Default: INFO.
LOG_OUTPUT○Dove scrivere i log: stdout o percorso del file.

Obbligatorio   Opzionale

Comportamento di sicurezza: le richieste senza un header Authorization valido vengono rifiutate prima di aprire una connessione al database.

Avvia il server:

./pgarachne -config .env

Vedi anche

Documentazione correlata

← Installazione Esempio Hello World →