electric-cherry/docs/guides/getting-started.md

# 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.
- A signed agent release and its public key published in the trusted repository.
- Outbound HTTPS access from game hosts to the controller and public repository.
- 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.

Before building for game hosts, obtain the publisher's signed `static/agent`
artifacts and matching source revision, or follow
[Publishing signed releases](native-hosts.md#publishing-signed-releases)
for your own build. Normal builds preserve signatures for identical artifacts;
source changes require a new offline signature. An unsigned controller can run,
but hosts reject its agent installation and updates.

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

Proxy the HTTPS address to controller port 3000. Enable gzip or Brotli compression
at the HTTPS reverse proxy for HTML (`text/html`) and JSON (`application/json`),
including server-rendered pages, page data, and API responses. The build already
precompresses static JavaScript and CSS assets; dynamically generated responses
need compression at the proxy.

Configure `ADDRESS_HEADER` and `XFF_DEPTH` for your trusted proxy so login limits
use each client's address. Leave `ADDRESS_HEADER` empty for direct connections;
see the [proxy configuration guide](authentication.md#proxy-and-local-development)
before enabling forwarded addresses.

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 **Admin → Users**. The
[access guide](authentication.md) explains roles, proxy configuration, and
password recovery.

## Prepare a game host

1. Open **Releases → 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. Ensure the release publisher has [published its public key and signed release](native-hosts.md#publishing-signed-releases).
   Hosts fetch the key automatically during installation and before every update
   check; there is no manual key-copy step.
3. Open **Fleet → Hosts → Add Host**, configure the host's game-port range and
   bind address, and run the generated enrollment command. It downloads the
   installer from the fixed public repository URL before running it. Check that
   the installer source is the known repository, independent of the controller.
4. 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.
Existing hosts using updater protocol 1 need a
[trusted installer migration](native-hosts.md#automatic-agent-updates) before
controller-independent release verification takes effect.

## Launch your first server

1. Save Plutonium server keys in the T5 or T6 pool under **Admin → Keys**.
2. Open **Create server** and choose a game and map. Readiness checks run
   automatically. For a reusable lineup, use **Fleet → Collections** instead.
3. Resolve any launch blockers and choose **Launch server**. 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.

## Script release versions

Every new script upload needs a release version in `MAJOR.MINOR.PATCH` form,
for example `1.2.0`. Enter a version for each file in the upload drawer, script
page, or beta replacement dialog. Versions belong to individual scripts; a batch
can contain different versions.

To fill empty fields automatically, choose `versions.json` from the same source
checkout as your scripts. Cherry matches exact, case-sensitive filenames (such as
`tws_t5_hud.gsc`) and leaves entered values intact. Review the values before
uploading. A manifest identifies source releases; it does not verify file contents.

Changing a script requires a new release version. Reuploading identical bytes with
the same version reuses the saved release; different bytes with that version are
rejected. Older release versions can be imported. Cherry keeps its upload number
separately, displaying labels such as `1.2.0 (upload 7)`.

Historical scripts without a release label display `Unversioned (upload N)` and
remain available for testing, promotion, and rollback. Cherry does not infer old
versions from today's manifest or rewrite historical records. Uploading the same
bytes with an explicit version creates a separate labeled record when needed.
Plugins retain optional publisher tags; configurations retain automatic upload
numbers.

API clients must include multipart `releaseVersion` when creating a script with
`POST /api/scripts` or uploading with `POST /api/scripts/:id/versions`. Missing or
invalid versions return HTTP 400; conflicting contents return HTTP 409. The
version upload response reports `reused: true` for an existing identical release.

## 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
[pilot procedure](autoscaling.md#pilot) before enabling live actions.