Faraday Server Configuration Reference¶

Faraday Server v5.19.0 — Complete server.ini and runtime settings reference.

Configuration Architecture¶

Faraday uses a two-tier configuration system:

1. INI-based (server.ini) — Static settings loaded at server startup. Changes require a server restart. Managed by editing the file directly.

2. Database-backed (Settings API) — Dynamic settings stored in the PostgreSQL configuration table as JSON. Managed via faraday-manage settings or the REST API. Most changes take effect without restart.

Configuration Precedence¶

Settings are resolved in this order (highest priority first):

File Locations¶

All paths are relative to $FARADAY_HOME/.faraday/. The FARADAY_HOME environment variable defaults to /home/faraday (if it exists) or the current user's home directory.

INI-Based Settings (server.ini)¶

[faraday_server] Section¶

Core server behavior settings.

Commercial-Only Settings¶

The following settings appear in the documentation but are only available in Faraday Professional / Corporate editions. They are not present in the community edition config.py:

Celery Broker URL Processing¶

When setting celery_broker_url or celery_backend_url, the server applies this logic:

1. If the value contains no colon (e.g., redis), it is treated as a hostname and expanded to redis://HOSTNAME:6379/0.
2. If the value contains a colon, it checks for a recognized scheme (redis, rediss, amqp, amqps). If found, it is used as-is.
3. Otherwise, redis:// is prepended.

Examples:

# All equivalent for a Redis broker on "myredis" host:
celery_broker_url = myredis
celery_broker_url = redis://myredis:6379/0

# RabbitMQ broker:
celery_broker_url = amqp://user:pass@rabbitmq:5672/vhost

# Redis with TLS:
celery_broker_url = rediss://redis-host:6380/0

[database] Section¶

Format:

postgresql+psycopg2://USERNAME:PASSWORD@HOST[:PORT]/DATABASE

Examples:

[database]
# Local PostgreSQL
connection_string = postgresql+psycopg2://faraday_postgresql:secret@localhost/faraday

# Remote PostgreSQL on custom port
connection_string = postgresql+psycopg2://faraday:P@ssw0rd@db.example.com:5433/faraday_prod

# Docker (set via PGSQL_* environment variables)
connection_string = postgresql+psycopg2://postgres:postgres@db/faraday

SQLAlchemy Connection Pool¶

The server configures the SQLAlchemy connection pool with these fixed values:

Maximum simultaneous database connections: pool_size + max_overflow = 40.

[storage] Section¶

[logger] Section¶

Log File Locations¶

[limiter] Section¶

[gitlab_integration] Section¶

Database-Backed Settings¶

These settings are stored in the PostgreSQL configuration table and managed via:

• CLI: faraday-manage settings -a list|show|update|clear <name>
• API: GET/PUT /_api/v3/settings/<name>

Changes take effect without a server restart (some may trigger a thread restart via SIGUSR1 internally).

SMTP Settings¶

Setting name: smtp

Configure via CLI:

faraday-manage settings -a update smtp --data '{
  "enabled": true,
  "host": "smtp.example.com",
  "port": 587,
  "ssl": true,
  "username": "notifications@example.com",
  "password": "secret",
  "sender": "faraday@example.com"
}'

ELK Settings¶

Setting name: elk

Dashboard Settings¶

Setting name: dashboard

Reports Settings¶

Setting name: reports

Query Limits Settings¶

Setting name: query_limits

Managing Settings via CLI¶

# List all configurable settings
faraday-manage settings -a list

# Show current value of a setting
faraday-manage settings -a show smtp

# Update a setting
faraday-manage settings -a update smtp --data '{"enabled": true, "host": "smtp.example.com"}'

# Clear a setting (reset to defaults)
faraday-manage settings -a clear smtp

Environment Variables¶

Core Variables¶

Docker-Only Variables¶

These are used by the Docker entrypoint script (docker/entrypoint.sh):

* Required only on first run (when server.ini does not yet exist).

Internal Variables (Set Automatically)¶

Flask Application Settings¶

These are configured internally by app.py and cannot be changed via server.ini:

Command-Line Arguments¶

The faraday-server command accepts these startup arguments:

Minimal Configuration Example¶

A minimal server.ini for a bare-metal installation:

[faraday_server]
port = 5985
bind_address = 127.0.0.1

[database]
connection_string = postgresql+psycopg2://faraday_postgresql:YOUR_PASSWORD@localhost/faraday

[storage]
path = /home/faraday/.faraday/storage

Production Configuration Example¶

A production server.ini with security hardening:

[faraday_server]
port = 5985
bind_address = 127.0.0.1
session_timeout = 8
api_token_expiration = 86400
idle_session_timeout = 1800
debug = false
delete_report_after_process = true
celery_enabled = true
celery_broker_url = redis://redis.internal:6379/0
celery_backend_url = redis://redis.internal:6379/0

[database]
connection_string = postgresql+psycopg2://faraday:STRONG_PASSWORD@db.internal:5432/faraday_prod

[storage]
path = /data/faraday/storage

[limiter]
enabled = true
login_limit = 5/minutes

[logger]
use_rfc5424_formatter = true

Troubleshooting¶

Server won't start — "Address already in use"¶

Another process is using port 5985. Check with:

lsof -i :5985

Change the port in server.ini or stop the conflicting process.

Sessions expire too quickly¶

Check both session_timeout (overall session lifetime in hours) and idle_session_timeout (inactivity timeout in seconds). Set idle_session_timeout = 0 to disable idle timeout.

Celery workers not processing tasks¶

1. Verify Redis/RabbitMQ is running and accessible.
2. Check that celery_enabled = true in server.ini.
3. Verify celery_broker_url resolves to the correct broker.
4. Check ~/.faraday/logs/celery.log for errors.

Secret key changed — all users logged out¶

The secret_key is auto-generated on first run and stored in server.ini. If the file is deleted or regenerated, all existing sessions become invalid. Back up your server.ini before reinstalling.

Database connection pool exhaustion¶

If you see "QueuePool limit" errors, the server has exhausted its 40 connection limit (pool_size=20 + max_overflow=20). This can occur with many concurrent users. The pool settings are hard-coded and require a code change to modify.