Configuration
The .env keys the CLI manages, how to size memory, and where each setting actually lives.
Beacon splits configuration into two layers with clear ownership:
- Infrastructure — ports, ingress, secrets, the pinned version, the
Minecraft image. Set in
.envin the deployment directory, owned by the CLI. - Gameplay & operations — difficulty, game mode, world generation, the allowlist, MOTD, backup schedules. Managed in the dashboard, stored in the database.
Don't hand-edit compose files or server.properties
The CLI regenerates docker-compose.yml and friends on beacon upgrade /
beacon restart, and Beacon generates server.properties from the dashboard.
Hand edits to those files are not authoritative. Change infrastructure in
.env, and gameplay in the dashboard.
Key .env values
beacon create writes these for you; you'll mostly only revisit them to tune
memory or change the Minecraft version. After editing .env, apply changes
with beacon restart.
| Key | Purpose |
|---|---|
BEACON_VERSION | Pinned Beacon release (concrete version, never latest). |
MC_IMAGE | The itzg/minecraft-server image tag (e.g. :java25). |
MC_VERSION | The Minecraft release (e.g. 26.1.2). |
MC_MEMORY | JVM heap for the server (e.g. 4G). |
MC_HOST_PORT | Host TCP port published to players (default 25565). |
MC_PUBLIC_HOST | Friendly address shown in the How to join panel. |
PUBLIC_APP_URL | The dashboard's public URL. |
COMPOSE_PROFILES | tailscale or custom-domain — selects the ingress. |
TS_AUTHKEY | Tailscale auth key (Tailscale mode). |
BEACON_DOMAIN / BEACON_ACME_EMAIL | Domain + ACME contact (custom-domain mode). |
MC_RCON_PASSWORD, ADMIN_RPC_TOKEN, BEACON_SESSION_SECRET | Generated secrets — leave them alone. |
Pin a concrete version
BEACON_VERSION must be an exact release — the moving latest tag is
rejected because it hides what's running and breaks update detection.
beacon doctor warns if an install drifts to latest or unset.
Sizing memory
MC_MEMORY is the JVM heap, not total host memory — and you don't add headroom
by hand. The CLI sizes the Minecraft container with off-heap headroom on top of
the heap, and beacon up warns if the beacons on a host over-commit its RAM.
Pick a VPS that fits the sizing table, then
set MC_MEMORY to the heap you want and apply:
# in .env
MC_MEMORY=6Gbeacon restartMinecraft version and loader
MC_IMAGE + MC_VERSION pin the server. The default loader is Paper; you
can switch the loader from the dashboard's server settings once running. Pin a
known-good MC_VERSION and check release notes before bumping — world upgrades
are effectively one-way (see Updating).
Where gameplay settings live
Difficulty, game mode, PVP, view distance, MOTD, max players, and the like are server settings in the dashboard — they apply to whatever world is loaded, matching Minecraft's own model. World-generation choices (seed, level type, structures, hardcore) belong to a world and are set when you create one.
The allowlist is always enforced — Beacon is the access manager, maintaining it over RCON from the dashboard's People page. There's no toggle to disable allowlist enforcement; that's a deliberate safety invariant.
See Managing your beacon for the dashboard surfaces.