114 lines
5.7 KiB
Markdown
114 lines
5.7 KiB
Markdown
# 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. 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](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. 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 **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.
|
|
|
|
## 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.
|