Configuring BigFred with the loco-server.conf File

Set BigFred’s HTTP address, JWT secret, Redis settings, log level, and more using the loco-server.conf file or command-line flags.

loco-server reads its settings from a plain-text KEY=VALUE configuration file. On hub images this file lives at /data/etc/loco-server.conf. For manual installs you can place it there or pass all settings as command-line flags. Every setting has a built-in default so the server runs without any configuration at all — but for a production deployment you will want to set at least a persistent JWT secret.

Configuration File

Location

Path	Purpose
/data/etc/loco-server.conf	Live configuration — read at startup, edit to persist changes
/data/etc/loco-server.conf.defaults	Reference file — rewritten with built-in defaults on every start, not read at runtime

On a fresh install, if loco-server.conf does not exist, loco-server creates it with all defaults filled in so you have a working starting point. Use loco-server.conf.defaults as a reference for every supported key and its default value.

Format

The file uses a simple KEY=VALUE (dotenv) format:

/data/etc/loco-server.conf

# Lines beginning with # are comments
# Blank lines are ignored
# Quotes around values are stripped automatically

HTTP=0.0.0.0:8080
JWT_SECRET=my-secret-here
LOG_LEVEL=info

Accepted boolean values for true/false keys: true, false, 1, 0, yes, no, on, off.

Full Configuration Reference

Key	Default	CLI flag	Description
HTTP	0.0.0.0:8080	--http	HTTP listen address. Change the port or bind to a specific interface.
DB	bigfred.db	--db	Path to the SQLite database file. Use an absolute path for a service installation.
JWT_SECRET	(random per-run)	--jwt-secret	Secret used to sign session tokens. Set this for production — see the note below.
CORS_ORIGIN	http://localhost:5173, http://127.0.0.1:5173	--cors-origin	Comma-separated list of allowed CORS origins. The defaults cover the Vite dev server only.
SECURE_COOKIE	false	--secure-cookie	Sets the Secure flag on session cookies. Required when serving over HTTPS — see the warning below.
NO_SUPERVISOR	false	--no-supervisor	Skip the embedded supervisord process manager. Disables automatic Valkey and DCC bus daemon management. Only use this in development.
LOG_LEVEL	info	--log-level	Logging verbosity. Accepted values: debug, info, warn, error.
REDIS_BIN	valkey-server	--redis-bin	Path or name of the Valkey/Redis binary used by the managed sidecar.
REDIS_BIND	127.0.0.1	--redis-bind	Interface the managed Valkey daemon binds on. Loopback is correct for a local sidecar.
REDIS_PORT	6379	--redis-port	TCP port for the managed Valkey daemon.
REDIS_DATA_DIR	(server working directory)	--redis-data-dir	Working directory for the managed Valkey daemon. Leave blank to use the default location chosen by loco-server.
REDIS_ADDR	(REDIS_BIND:REDIS_PORT)	--redis-addr	Dial address loco-server uses to reach Valkey. Defaults to REDIS_BIND:REDIS_PORT.
REDIS_EXTERNAL	false	--redis-external	When true, do not spawn a managed Valkey daemon — dial REDIS_ADDR instead. Use this when you run your own Redis/Valkey instance.
REDIS_AUTO_DETECT	true	--redis-auto-detect	When true, skip spawning the managed Valkey daemon if something is already listening at REDIS_ADDR.
REDIS_RDB_SAVE	60:100	--redis-rdb-save	Comma-separated seconds:changes pairs that control RDB snapshot frequency (e.g. 60:100 saves if 100 keys changed in 60 seconds). Pass an empty string to disable.
REDIS_NO_PERSIST	false	--redis-no-persist	Disable RDB snapshots for the managed Valkey daemon. Useful for ephemeral/test deployments where persistence is not needed.
ENABLE_TELEMETRY	false	--enable-telemetry	Start Grafana Alloy via supervisord and export OTLP metrics from loco-server and the DCC bus daemons.
TELEMETRY_CONFIG	(built-in path)	--telemetry-config	Path to the Grafana Alloy configuration file. Only used when ENABLE_TELEMETRY=true.

Key Settings Explained

JWT_SECRET — Sessions That Survive Restarts

JWT_SECRET is the single most important setting to configure before going into regular operation. Without it, loco-server generates a fresh random secret each time it starts, which immediately invalidates all active sessions. Every operator is logged out on every server restart.

Generate a strong secret once and set it in loco-server.conf (or via the environment variable — see below):

# Generate a 64-character hex secret
openssl rand -hex 32

SECURE_COOKIE — Required for HTTPS Deployments

If you are serving BigFred over HTTPS (recommended for any deployment outside your home network), you must set SECURE_COOKIE=true. Without it, browsers will reject session cookies on HTTPS origins and no one will be able to log in.

Conversely, do not set SECURE_COOKIE=true on a plain http:// deployment — browsers won’t send the cookie over non-secure connections and login will silently fail.

Minimal Production Configuration

Here is a recommended starting point for a permanent installation. Copy it to /data/etc/loco-server.conf and replace the JWT_SECRET value with a secret generated by openssl rand -hex 32.

/data/etc/loco-server.conf

HTTP=0.0.0.0:8080
DB=/opt/bigfred/bigfred.db

# Generate with: openssl rand -hex 32
JWT_SECRET=change-me-to-a-random-64-char-hex-string

# Set to true only when serving over HTTPS
SECURE_COOKIE=false

LOG_LEVEL=info

Environment Variable Override

One setting can also be provided via an environment variable, which is useful for secrets management in containerised or systemd-managed deployments:

Environment variable	Overrides	Notes
BIGFRED_JWT_SECRET	JWT_SECRET	Takes precedence over both the config file and the --jwt-secret flag
BIGFRED_LOG_LEVEL	LOG_LEVEL	Takes precedence over both the config file and the --log-level flag

Example in a systemd unit:

/etc/systemd/system/bigfred.service (excerpt)

[Service]
Environment="BIGFRED_JWT_SECRET=your-64-char-hex-secret-here"

Precedence Order

When the same setting is provided in multiple places, loco-server applies them in this order (highest to lowest priority):

1. CLI flag (e.g. --jwt-secret)
2. Environment variable (e.g. BIGFRED_JWT_SECRET)
3. Config file (/data/etc/loco-server.conf)
4. Built-in default