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, plus its publisher's public key and reviewed installer obtained through a trusted channel independent of the controller.
• 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:

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

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.

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 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. Provision release trust: independently verify the publisher key's full fingerprint, install its binary public key at /etc/electric-cherry/release-signing.gpg, and copy the reviewed installer to ./electric-cherry-install.sh on the host. Both come from the trusted publisher.
3. Open Fleet → Hosts → Add Host, configure the host's game-port range and bind address, and run the generated enrollment command from the directory containing that local installer. Do not pipe controller-downloaded code into a root shell.
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 for storage layout, network access, and recovery. Existing hosts using updater protocol 1 need a trusted installer migration 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 and Collections 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 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 for scheduled work and Fleet settings for concurrency and retention controls.

For lobby autoscaling, start with the documented pilot procedure before enabling live actions.