> ## Documentation Index
> Fetch the complete documentation index at: https://dcc-5ccd5152.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```ini /data/etc/loco-server.conf theme={null}
# 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

<Note>
  `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):

  ```bash theme={null}
  # Generate a 64-character hex secret
  openssl rand -hex 32
  ```
</Note>

### SECURE\_COOKIE — Required for HTTPS Deployments

<Warning>
  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.
</Warning>

## 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`.

```ini /data/etc/loco-server.conf theme={null}
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:

```ini /etc/systemd/system/bigfred.service (excerpt) theme={null}
[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**