3 min read

Quickstart

  1. Install PgArachne
  2. Configure environment
  3. Set up security and auth
  4. Deploy behind HTTPS proxy

Configuration

PgArachne loads configuration from environment variables or a file.

Note: schema.sql attempts to create the pgarachne_admin role and grant it to pgarachne. If you run the script without superuser privileges, role creation is skipped. Create the role and grant it manually if needed.
The proxy user (DB_USER) must be a member of pgarachne and pgarachne_admin to verify and mint API tokens.
Security Note: PgArachne does not handle database passwords in the configuration file. Rely on the standard PostgreSQL .pgpass file mechanism (or PGPASSWORD system variable) for authentication.
Tip: If you run PgArachne behind a reverse proxy, set TRUSTED_PROXIES so client IPs are resolved correctly and rate limiting cannot be spoofed.
Search Order: If no configuration file is specified via CLI, it searches in:
  1. Current directory: ./pgarachne.env (All OS)
  2. User config:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. System config: /etc/pgarachne/pgarachne.env (Linux/macOS only)

Minimal Configuration Example

This is all you need to get started:

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

Required variables: DB_HOST, DB_PORT, DB_USER, JWT_SECRET.

Quick Validation Checklist

  • JWT_SECRET is long, random, and not reused across environments.
  • DB_USER can switch only to expected roles (verify role membership grants).
  • TRUSTED_PROXIES is set when running behind a reverse proxy.
  • LOGIN_RATE_LIMIT is enabled for internet-facing deployments.
  • METRICS_LISTEN_ADDR is private (for example 127.0.0.1:9090).

Configuration Reference

VariableRequiredDescription
Database Connection
DB_HOST✓PostgreSQL server address (e.g., localhost).
DB_PORT✓Database port.
DB_USER✓The database user PgArachne connects with.
DB_SSLMODE○PostgreSQL SSL mode. Default: disable.
DB_SSLROOTCERT○Path to CA root certificate (PEM).
DB_SSLCERT○Path to client certificate (PEM).
DB_SSLKEY○Path to client private key (PEM).
HTTP Server
HTTP_PORT○Port to listen on. Default: 8080.
API_PREFIX○First URL path segment for all database endpoints (/jsonrpc, /sse, /mcp). Default: db, giving routes like /db/:database/jsonrpc. Set to api to match legacy paths. Only letters, digits, hyphens and underscores are allowed.
PID_FILE○Path to daemon PID file used by -start/-stop. Default: OS user cache dir (fallback: temp dir).
ALLOWED_ORIGINS○CORS settings. Comma separated list of allowed domains (e.g. https://myapp.com). Default: *.
STATIC_FILES_PATH○Absolute path to serve static files (Explorer/Frontend).
Security (JWT)
JWT_SECRET✓A long, random string used to sign session tokens.
JWT_EXPIRY_HOURS○Session validity in hours. Default: 8.
LOGIN_RATE_LIMIT○Max login attempts per window. Default: 5. Set 0 to disable.
LOGIN_RATE_WINDOW○Rate limit window duration. Default: 1m.
Login rate limiting is per instance (in-memory). In multi-instance deployments, use a shared limiter if you need global enforcement.
TRUSTED_PROXIES○Trusted proxy IPs/CIDRs for X-Forwarded-For handling. Comma-separated. If empty, forwarded headers are ignored and client IP is taken from the direct connection.
MAX_REQUEST_BYTES○Max request body size in bytes. Default: 2097152.
METRICS_ENABLED○Enable dedicated metrics endpoint. Default: true.
METRICS_LISTEN_ADDR○Metrics listener address (host:port). Default: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Max channels per SSE connection. Default: 8.
SSE_MAX_CLIENTS○Max concurrent SSE clients per database. Default: 1000.
SSE_CLIENT_BUFFER○SSE per-client buffer size (messages). Default: 64.
SSE_SEND_TIMEOUT○Max time to wait when sending to a slow client. Default: 2s.
SSE_HEARTBEAT○Heartbeat interval for SSE connections. Default: 20s.
SSE_IDLE_TIMEOUT○Idle timeout without notifications. Default: 90s.
Logging
LOG_LEVEL○Verbosity: DEBUG, INFO, WARN, ERROR. Default: INFO.
LOG_OUTPUT○Where to write logs: stdout or file path.

Required   Optional

Security behavior: requests without a valid Authorization header are rejected before opening a database connection.

Start the server:

./pgarachne -config .env

See also

Related Docs

← Installation JSON-RPC (Hello World) →