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:

Current directory: ./pgarachne.env (All OS)
User config:
- Linux / macOS: ~/.config/pgarachne/pgarachne.env
- Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
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.

Configuration Reference

Variable	Required	Description
Database Connection
`DB_HOST`	Yes	PostgreSQL server address (e.g., `localhost`).
`DB_PORT`	Yes	Database port.
`DB_USER`	Yes	The database user PgArachne connects with.
`DB_SSLMODE`	No	PostgreSQL SSL mode. Default: `disable`.
`DB_SSLROOTCERT`	No	Path to CA root certificate (PEM).
`DB_SSLCERT`	No	Path to client certificate (PEM).
`DB_SSLKEY`	No	Path to client private key (PEM).
HTTP Server
`HTTP_PORT`	No	Port to listen on. Default: `8080`.
`ALLOWED_ORIGINS`	No	CORS settings. Comma separated list of allowed domains (e.g. `https://myapp.com`). Default: `*`.
`STATIC_FILES_PATH`	No	Absolute path to serve static files (Explorer/Frontend).
Security (JWT)
`JWT_SECRET`	Yes	A long, random string used to sign session tokens.
`JWT_EXPIRY_HOURS`	No	Session validity in hours. Default: `8`.
`LOGIN_RATE_LIMIT`	No	Max login attempts per window. Default: `5`. Set `0` to disable.
`LOGIN_RATE_WINDOW`	No	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`	No	Trusted proxy IPs/CIDRs for `X-Forwarded-For` handling. Comma-separated.
`MAX_REQUEST_BYTES`	No	Max request body size in bytes. Default: `2097152`.
`SSE_MAX_CHANNELS`	No	Max channels per SSE connection. Default: `8`.
`SSE_MAX_CLIENTS`	No	Max concurrent SSE clients per database. Default: `1000`.
`SSE_CLIENT_BUFFER`	No	SSE per-client buffer size (messages). Default: `64`.
`SSE_SEND_TIMEOUT`	No	Max time to wait when sending to a slow client. Default: `2s`.
`SSE_HEARTBEAT`	No	Heartbeat interval for SSE connections. Default: `20s`.
`SSE_IDLE_TIMEOUT`	No	Idle timeout without notifications. Default: `90s`.
Logging
`LOG_LEVEL`	No	Verbosity: `DEBUG`, `INFO`, `WARN`, `ERROR`. Default: `INFO`.
`LOG_OUTPUT`	No	Where to write logs: `stdout` or file path.

Start the server:

./pgarachne -config .env

← Installation Hello World Example →