4 min de lecture

Démarrage rapide

  1. Installez PgArachne
  2. Configurez l’environnement
  3. Configurez sécurité et auth
  4. Déployez derrière un proxy HTTPS

Configuration

PgArachne charge la configuration depuis des variables d’environnement ou un fichier.

Note : schema.sql tente de créer le rôle pgarachne_admin et de l’accorder à pgarachne. Sans droits superuser, la création est ignorée. Créez le rôle et le grant manuellement si besoin.
L’utilisateur proxy (DB_USER) doit être membre de pgarachne et pgarachne_admin pour vérifier et créer des tokens API.
Note de sécurité : PgArachne ne gère pas les mots de passe de la base de données dans le fichier de configuration. Il s’appuie sur le mécanisme standard du fichier .pgpass de PostgreSQL (ou la variable système PGPASSWORD) pour l’authentification.
Astuce : Si PgArachne est derrière un reverse proxy, définis TRUSTED_PROXIES pour résoudre correctement l’IP client et éviter le spoofing du rate limit.
Ordre de recherche : Si aucun fichier de configuration n’est spécifié via CLI, il cherche :
  1. Répertoire actuel : ./pgarachne.env (Tous les OS)
  2. Configuration utilisateur :
    • Linux/macOS : ~/.config/pgarachne/pgarachne.env
    • Windows : %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Configuration système : /etc/pgarachne/pgarachne.env (Linux/macOS uniquement)

Exemple de configuration minimale

Voici tout ce dont vous avez besoin pour commencer :

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

Checklist rapide de validation

  • JWT_SECRET est long, aléatoire et différent selon les environnements.
  • DB_USER ne peut basculer que vers les rôles attendus (vérifier les grants de membership).
  • TRUSTED_PROXIES est défini si PgArachne est derrière un reverse proxy.
  • LOGIN_RATE_LIMIT est activé pour les déploiements exposés à internet.
  • METRICS_LISTEN_ADDR reste privé (par exemple 127.0.0.1:9090).

Référence de configuration

VariableRequisDescription
Connexion Base de Données
DB_HOST✓Adresse du serveur PostgreSQL (ex : localhost).
DB_PORT✓Port de la base de données.
DB_USER✓L’utilisateur de base de données avec lequel PgArachne se connecte.
DB_SSLMODE○Mode SSL PostgreSQL. Par défaut : disable.
DB_SSLROOTCERT○Chemin vers le certificat racine CA (PEM).
DB_SSLCERT○Chemin vers le certificat client (PEM).
DB_SSLKEY○Chemin vers la clé privée du client (PEM).
Serveur HTTP
HTTP_PORT○Port d’écoute. Défaut : 8080.
API_PREFIX○Premier segment du chemin URL pour tous les endpoints de base de données (/jsonrpc, /sse, /mcp). Par défaut : db, donnant des routes comme /db/:base_de_donnees/jsonrpc. Mettre à api pour les chemins legacy. Seuls les lettres, chiffres, tirets et underscores sont autorisés.
PID_FILE○Chemin du fichier PID du daemon utilisé par -start/-stop. Par défaut : cache utilisateur (fallback : dossier temporaire).
ALLOWED_ORIGINS○Paramètres CORS. Liste séparée par des virgules des domaines autorisés (ex : https://monapp.com). Défaut : *.
STATIC_FILES_PATH○Chemin absolu pour servir les fichiers statiques (Explorer/Frontend).
Sécurité (JWT)
JWT_SECRET✓Une longue chaîne aléatoire utilisée pour signer les jetons de session.
JWT_EXPIRY_HOURS○Validité de la session en heures. Défaut : 8.
LOGIN_RATE_LIMIT○Nombre maximum de tentatives de connexion par fenêtre. Par défaut : 5. 0 désactive.
LOGIN_RATE_WINDOW○Durée de la fenêtre de limitation. Par défaut : 1m.
Le rate limit de login est par instance (en mémoire). En multi-instance, utilisez un limiteur partagé.
TRUSTED_PROXIES○Proxys de confiance (IP/CIDR) pour X-Forwarded-For. Séparés par des virgules. Si vide, les en-têtes forwardés sont ignorés et l’IP client est prise depuis la connexion directe.
MAX_REQUEST_BYTES○Taille maximale du body en octets. Par défaut : 2097152.
METRICS_ENABLED○Active le endpoint dédié aux métriques. Par défaut : true.
METRICS_LISTEN_ADDR○Adresse du listener de métriques (host:port). Par défaut : 127.0.0.1:9090.
SSE_MAX_CHANNELS○Nombre maximal de canaux par connexion SSE. Par défaut : 8.
SSE_MAX_CLIENTS○Nombre maximal de clients SSE simultanés par base. Par défaut : 1000.
SSE_CLIENT_BUFFER○Buffer SSE par client (nombre de messages). Par défaut : 64.
SSE_SEND_TIMEOUT○Délai max pour envoyer à un client lent. Par défaut : 2s.
SSE_HEARTBEAT○Intervalle de heartbeat pour SSE. Par défaut : 20s.
SSE_IDLE_TIMEOUT○Délai d’inactivité sans notifications. Par défaut : 90s.
Logging
LOG_LEVEL○Verbosité : DEBUG, INFO, WARN, ERROR. Défaut : INFO.
LOG_OUTPUT○Où écrire les logs : stdout ou chemin du fichier.

Obligatoire   Optionnel

Comportement de sécurité : les requêtes sans en-tête Authorization valide sont rejetées avant l’ouverture d’une connexion à la base.

Démarrez le serveur :

./pgarachne -config .env

Voir aussi

Documentation liée

← Installation Exemple Hello World →