loco-server CLI: BigFred Backend Command Reference

Reference for the loco-server command that starts the BigFred backend. Key flags for HTTP address, database path, JWT secret, Redis, and logging.

loco-server is the binary that runs the BigFred backend. When you start it, it brings up the HTTP and WebSocket server that the web UI connects to, manages a Redis/Valkey sidecar via supervisord for real-time state, and spawns a dcc-bus daemon for each configured command station. For most deployments you run it once on your hub and leave it running.

Basic usage

# Start with all defaults (listens on 0.0.0.0:8080)
./loco-server

# Listen on a different address or port
./loco-server --http 0.0.0.0:9090

# Set a persistent JWT secret so sessions survive restarts
./loco-server --jwt-secret "$(openssl rand -hex 32)"

If you do not set a JWT secret, loco-server generates a random one at startup and logs a warning. All logged-in sessions will be invalidated whenever the server restarts. Set --jwt-secret (or the BIGFRED_JWT_SECRET environment variable) in any environment where session persistence matters.

---

Flag reference

Flag	Default	Description
--http	0.0.0.0:8080	HTTP listen address and port
--db	bigfred.db	Path to the SQLite database file
--jwt-secret	(random)	Hex or base64 secret used to sign session JWTs. Falls back to BIGFRED_JWT_SECRET, then generates a random per-run value
--secure-cookie	false	Set the Secure flag on session cookies. Enable this whenever the server is accessed over HTTPS
--log-level	info	Log verbosity: debug, info, warn, or error
--redis-external	false	Connect to an existing Redis/Valkey instance instead of the managed sidecar. When set, loco-server dials --redis-addr directly and does not spawn its own daemon
--redis-addr	(redis-bind:redis-port)	Redis dial address (host:port), used by both loco-server and dcc-bus. Defaults to the managed bind address and port when unset
--redis-no-persist	false	Disable RDB snapshots for the managed Redis daemon. Useful in ephemeral or low-write deployments where you do not need on-disk state
--enable-telemetry	false	Start Grafana Alloy via supervisord and export OTLP metrics for loco-server and dcc-bus
--no-supervisor	false	Skip supervisord entirely. Disables the Redis sidecar and dcc-bus process management. Intended for local development only

Do not use --no-supervisor in production. Without supervisord, the Redis sidecar and dcc-bus daemons are not started, which disables real-time throttle commands, drive leases, and takeover requests.

---

Environment variables

Variable	Description
BIGFRED_JWT_SECRET	Sets the JWT signing secret without putting it on the command line. Takes precedence over --jwt-secret if both are present. Use this in systemd unit files and container environments to keep the secret out of process listings
BIGFRED_LOG_LEVEL	Overrides the --log-level flag. Accepts the same values: debug, info, warn, error

Setting the JWT secret via the environment is the recommended approach for production deployments:

export BIGFRED_JWT_SECRET="$(openssl rand -hex 32)"
./loco-server

---

Configuration file

On hub images, loco-server reads settings from /data/etc/loco-server.conf at startup. The file uses a simple KEY=VALUE format (dotenv style); comments start with # and blank lines are ignored. CLI flags always override values in the file.

/data/etc/loco-server.conf

HTTP=0.0.0.0:8080
DB=/data/bigfred.db
# JWT_SECRET=          # empty = BIGFRED_JWT_SECRET env or random per-run secret
SECURE_COOKIE=true
LOG_LEVEL=info

REDIS_EXTERNAL=false
REDIS_NO_PERSIST=false

ENABLE_TELEMETRY=false

On every startup, loco-server also writes a fully-commented reference template to /data/etc/loco-server.conf.defaults. That file documents every supported key with its built-in default. It is not read at runtime — copy keys from it into loco-server.conf to apply changes.

For the full configuration key reference and persistence details, see the Configuration page.

---

The dcc-bus subcommand

loco-server includes a dcc-bus subcommand that is spawned automatically by supervisord — one instance per command station configured in the database. Each dcc-bus process owns the low-level DCC communication for one station and exchanges drive, function, and CV messages with loco-server over Redis.

# This is run automatically — you do not need to call it manually
loco-server dcc-bus ...

You should not need to run loco-server dcc-bus directly. If a dcc-bus daemon is not starting or is restarting unexpectedly, check the supervisord log files and increase --log-level to debug for more detail.