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

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

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: disable.
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. Impostare su api per i percorsi legacy. 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: *.
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.
JWT_EXPIRY_HOURS○Validità della sessione in ore. Default: 8.
LOGIN_RATE_LIMIT○Numero massimo di tentativi di login per finestra. Predefinito: 5. 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.
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

Documentazione correlata

← Installazione Esempio Hello World →