# Electric Cherry

A self-hosted dashboard for managing Plutonium T5 and T6 Zombies servers.
Electric Cherry handles your fleet, game files, releases, and maintenance from
one web interface. Game servers run on your hosts using Docker, Plutainer, and
a small Python agent.

![Fleet overview showing sample T5 and T6 lobbies, player counts, and match rounds](docs/assets/fleet.png)

*Fleet overview with sample data.*

## Features

- Launch individual servers or saved collections of maps and lobbies.
- Monitor players, host capacity, match history, and leaderboards.
- Manage scripts, plugins, and configuration with beta testing and rollback.
- Queue maintenance around active games and scale spare lobbies with opt-in policies.
- Control access with administrator, operator, and viewer accounts.

## Getting started

You'll need Docker Compose for the controller, an HTTPS reverse proxy, and
Debian 12 or 13 amd64 game hosts. Bring your own game files and Plutonium server keys.

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

Edit `.env`: use the generated secret for `EC_SETUP_TOKEN`, set `EC_PUBLIC_URL`
to your HTTPS address, and choose a persistent `EC_DATA_DIR`. Then start the
controller and proxy your HTTPS address to port 3000:

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

Open the dashboard and create your first administrator with the setup token.
Remove the token from `.env` afterward and recreate the controller with
`docker compose up -d`.

1. Upload your T5 or T6 folder, including DLC, under **Releases → Game files**.
2. Add a machine under **Fleet → Hosts** and run its generated enrollment command.
3. Save your Plutonium keys under **Admin → Keys**.
4. Wait for host setup to finish, then launch a server or collection.

See the [setup guide](docs/guides/getting-started.md) for telemetry, storage,
and the first launch. Host agents connect outbound over HTTPS; the controller
doesn't need a Docker socket or direct access to your game-server files.

## Documentation

- [Documentation index](docs/README.md) — setup, operations, releases, and analytics.
- [Development guide](docs/development/README.md) — architecture, checks, and diagnostics.
- [Autoscaling plan](docs/plans/lobby-autoscaling-plan.md) — design and remaining pilot work.
- [Idle CPU research](docs/research/t5-t6-idle-cpu-research.md) — experiments and tradeoffs.

## Development

The controller uses SvelteKit, TypeScript, and SQLite. The host agent uses the
Python 3 standard library. For local development, install Node.js 22 and Python 3:

```sh
npm ci
npm run agent:package
export EC_SETUP_TOKEN=$(openssl rand -hex 32)
export BETA_ARCHIVE_DIR=./data/beta-archive
EC_AUTH_ALLOW_HTTP=true npm run dev
```

Open `http://localhost:3000` and use the setup token from your shell. The local
database defaults to `./data/cherry.db`; keep it separate from production data.

```sh
npm run check
npm test
npm run test:agent
npm run build
```