# Getting started

Electric Cherry runs a web controller and an agent on each game host. The
controller stores fleet metadata in SQLite and uploaded game files on disk.
Agents run Docker/Plutainer locally and connect outbound to the controller over
HTTPS. Running game containers continue through controller or agent outages.

## Requirements

- A controller machine with Docker Compose and an HTTPS reverse proxy.
- Debian 12 or 13 amd64 game hosts with storage for game files and instances.
- Your complete T5 or T6 game folders, including the DLC you intend to host.
- Plutonium server keys for each game, with one unused key per new concurrent lobby.

The controller does not need access to a Docker socket, game-host mounts, or
inbound RCON. Host agents handle local game commands and file operations.

## Start the controller

From the repository root:

```sh
cp .env.example .env
openssl rand -hex 32
```

Set these values in `.env`:

| Variable | Purpose |
| --- | --- |
| `EC_PUBLIC_URL` | The external HTTPS address of the dashboard. |
| `EC_SETUP_TOKEN` | The generated secret, used to create the first administrator. |
| `EC_DATA_DIR` | A persistent directory for the database, game files, and beta archives. |
| `EC_TELEMETRY_TOKEN` | A separate secret of at least 32 characters for game reporters. Generate it independently with the same command. |

For an existing installation, retain its original data directory. Compose
defaults to `/root/zombies/.electric-cherry`; choose a dedicated directory for a
new controller. See [.env.example](../../.env.example) for the other settings.

```sh
docker compose up -d --build
```

Proxy the HTTPS address to controller port 3000. Open the dashboard and follow
`/setup` to create the first administrator. Then remove `EC_SETUP_TOKEN` from
`.env` and run `docker compose up -d` to recreate the controller. Setup stays
closed once an account exists.

Add other users under **Administration → Users**. The
[access guide](authentication.md) explains roles, proxy configuration, and
password recovery.

## Prepare a game host

1. Open **Library → Game Files** and upload the complete local folder for T5 or
   T6, including DLC. Uploads can run before any host is enrolled. The latest
   verified upload becomes that game's default files.
2. Open **Fleet → Hosts → Add Host**, configure the host's game-port range and
   bind address, and run the generated enrollment command on the host.
3. Wait for automatic setup to prepare the Plutainer runtime and available game
   files. The host page reports download, verification, and readiness progress.

The installer sets up the Python agent as a systemd service and enables automatic
agent updates. It installs Docker if needed. Multiple instances share read-only
base game files; each instance has its own writable data. See
[Native hosts](native-hosts.md) for storage layout, network access, and recovery.

## Launch your first server

1. Save Plutonium server keys in the T5 or T6 pool under **Administration → Keys**.
2. Create a server, or build a reusable map lineup in **Fleet → Collections**.
3. Review the launch and apply it. Provisioning queues the work, then assigns a
   host and port when capacity is available.
4. Follow the operation until readiness checks pass, then verify that players
   can find and join the server.

Keys are shared across maps within their game. A launch assigns one available key
until the server is removed; stopped servers keep their keys. Optional key labels
can record the hostname chosen in Plutonium without binding the key to a map or
lobby. Electric Cherry does not change the hostname registered with Plutonium.

New launches use the latest verified game files and promoted configuration,
scripts, and plugins. Uploading newer game files does not restart existing
servers. Disruptive operations normally wait for a fresh empty lobby or a
verified stopped container. A rebuild removes the instance's writable files.
See [Provisioning](provisioning.md) and [Collections](collections.md) for details.

## Connect game telemetry

Configure your game reporter or plugin to send `EC_TELEMETRY_TOKEN` in an
authorization header to `POST /api/telemetry`. This credential is separate from
browser login, setup, and host enrollment. Ingestion is disabled until the
controller has a valid telemetry token.

The [game reporter protocol](beta-test-plans.md#game-reporter-protocol) defines
events and payloads for gameplay statistics and beta-test evidence. Electric
Cherry does not include the game reporter scripts themselves.

## Maintain the installation

Back up the complete controller data directory, including SQLite metadata and
published game files. Preserve that directory across upgrades. Review
[Maintenance](maintenance.md) for scheduled work and
[Fleet settings](settings.md) for concurrency and retention controls.

For lobby autoscaling, start with the documented
[dry run and pilot](autoscaling.md#dry-run-and-pilot) before enabling live actions.