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:

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. Ensure the release publisher has published its public key and signed release. 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 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.

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