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

# Install and Run BigFred loco-server on Your Layout

> Download and run the loco-server binary to install BigFred on a Raspberry Pi, NAS, or any Linux/macOS machine on your layout network.

BigFred runs as a single self-contained binary called `loco-server`. It bundles everything your layout needs in one process: the HTTP API, the embedded web frontend, DCC bus daemon management, and a Valkey (Redis-compatible) sidecar for real-time state. There is nothing extra to install alongside it — drop the binary on any Linux or macOS machine, run it, and open a browser.

## System Requirements

<CardGroup cols={3}>
  <Card title="Operating System" icon="linux">
    Linux (x86-64 or ARM) or macOS. A Raspberry Pi 4 or newer works well for a dedicated layout server.
  </Card>

  <Card title="Network" icon="network-wired">
    The server must be reachable by the devices your operators use and must have network access to your DCC command station.
  </Card>

  <Card title="Client" icon="browser">
    Any modern browser on the same network — desktop, tablet, or phone.
  </Card>
</CardGroup>

## Installation Steps

<Steps>
  ### Download the binary

  Download the latest `loco-server` release from the project's GitHub releases page. Pre-built Linux binaries (x86-64 and ARM) are attached to each tagged release.

  Once downloaded, make the binary executable:

  ```bash theme={null}
  chmod +x loco-server
  ```

  ### Start loco-server for the first time

  Run the binary from the directory where you want BigFred to store its database. By default `loco-server` listens on all interfaces at port **8080**.

  ```bash theme={null}
  # Start loco-server (listens on 0.0.0.0:8080 by default)
  ./loco-server
  ```

  On first boot, `loco-server` creates the SQLite database, seeds the bootstrap admin account, and prints a prominent warning with the default credentials:

  ```
  time="2025-01-15T10:22:05Z" level=info  msg="database opened, applying migrations"
  time="2025-01-15T10:22:05Z" level=info  msg="redis ready" source="managed"
  time="2025-01-15T10:22:05Z" level=warning msg="bootstrap system layout created — CHANGE THE ADMIN PIN AFTER FIRST LOGIN"
  time="2025-01-15T10:22:05Z" level=warning msg="bootstrap admin account created — CHANGE THE PIN AFTER FIRST LOGIN" login=admin pin=123456
  time="2025-01-15T10:22:05Z" level=info  msg="serving embedded frontend bundle at /"
  time="2025-01-15T10:22:05Z" level=info  msg="listening" addr="0.0.0.0:8080"
  ```

  <Warning>
    The default admin PIN is **123456**. Change it immediately after your first login. See the [First Login guide](/admin-guide/first-login) for instructions.
  </Warning>

  ### Confirm what was created

  After the first run you will find these new files in your working directory:

  | Path                | What it is                                                                 |
  | ------------------- | -------------------------------------------------------------------------- |
  | `bigfred.db`        | SQLite database — all layouts, users, vehicles, and settings               |
  | *(system temp dir)* | Supervisord configuration files for the Valkey sidecar and DCC bus daemons |

  Keep `bigfred.db` backed up. Losing it means losing all your layout data.

  ### Open the web UI

  On the machine running `loco-server`, or any device on the same network, open:

  ```
  http://<server-ip>:8080
  ```

  You should see the BigFred login screen. Log in with `admin` / `123456` and follow the [First Login guide](/admin-guide/first-login) to complete setup.

  ### (Optional) Run as a systemd service

  For a permanent installation — especially on a Raspberry Pi — create a systemd unit so `loco-server` starts automatically on boot.

  Create the file `/etc/systemd/system/bigfred.service`:

  ```ini /etc/systemd/system/bigfred.service theme={null}
  [Unit]
  Description=BigFred DCC Throttle Server
  After=network-online.target
  Wants=network-online.target

  [Service]
  Type=simple
  User=bigfred
  WorkingDirectory=/opt/bigfred
  ExecStart=/opt/bigfred/loco-server
  Restart=on-failure
  RestartSec=5

  # Persistent JWT secret so sessions survive restarts
  Environment="BIGFRED_JWT_SECRET=change-me-to-a-random-64-char-hex-string"

  [Install]
  WantedBy=multi-user.target
  ```

  Then enable and start the service:

  ```bash theme={null}
  # Create a dedicated user (optional but recommended)
  sudo useradd -r -s /sbin/nologin -d /opt/bigfred bigfred
  sudo mkdir -p /opt/bigfred
  sudo cp loco-server /opt/bigfred/
  sudo chown -R bigfred:bigfred /opt/bigfred

  # Enable and start
  sudo systemctl daemon-reload
  sudo systemctl enable bigfred
  sudo systemctl start bigfred

  # Check status
  sudo systemctl status bigfred
  ```
</Steps>

## Raspberry Pi Tips

<Tip>
  Assign your Raspberry Pi a **static IP address** on your layout network and note it in your layout documentation. Your operators need to know where to point their browsers, and the address should never change between operating sessions. Most home routers let you assign a static DHCP lease by MAC address — no changes needed on the Pi itself.
</Tip>

Once installed, continue with [Configuring BigFred](/admin-guide/configuration) to set a persistent JWT secret and tune other options, then complete the [First Login](/admin-guide/first-login) setup steps.