Updating Beacon

Beacon ships frequently during alpha. Updating pulls newer release images and recreates the stack; your world, backups, and .env are never touched. You can update two ways — both run the same health-gated flow.

Read the release notes first

Review the changelog before upgrading a live world, especially across Minecraft versions. Take a snapshot first.

From the dashboard (one click)

The dashboard checks for newer releases and shows a badge when one is available. Open Server → Updates, review the target version, and apply it. Beacon runs the upgrade through a helper container and shows live progress (pulling → recreating → waiting → succeeded). The page tolerates the brief moment the dashboard itself restarts. Expect 1–3 minutes of downtime.

If the new stack fails its health check, Beacon automatically rolls back to the previous version and compose files.

From the CLI

Apply a specific version

beacon upgrade 0.31.1 --yes

Pick from published releases interactively

beacon upgrade

beacon upgrade writes BEACON_VERSION, self-updates the CLI to match, re-renders the compose files from the new templates, pulls the target images, recreates only changed services, and waits for readiness. Without --yes it prints the plan first. --no-restart updates the pin and pulls without recreating.

By default beacon upgrade moves every beacon registered on the host to the chosen release: it resolves the release and self-updates the CLI once, then upgrades each beacon in turn, each with its own health-gated rollback so a bad release on one beacon can't take down the rest. Pass --dir <path> to upgrade a single deployment instead.

Upgrade just one beacon

beacon upgrade 0.31.1 --yes --dir /srv/survival

The CLI owns the compose templates

Because the CLI generates the compose files, upgrade and restart re-render them — so an install scaffolded by an older CLI picks up new service/env wiring instead of silently keeping stale YAML. beacon doctor flags this drift; beacon restart heals it without changing the version.

Rolling back

Image tags are immutable per release, so a rollback is exact — just upgrade to the older version:

beacon upgrade 0.31.0 --yes

If a release changed on-disk data and you need the world rolled back too, open beacon admin → Server → Backups and restore a snapshot taken before the upgrade.

Minecraft world upgrades are one-way

Newer Minecraft/Paper releases can change world storage in ways that can't be downgraded. Beacon blocks known unsafe version downgrades, but a code-level rollback can't undo world-data changes — restore a pre-upgrade backup for that. Always snapshot before a version bump.

Updating the CLI itself

beacon upgrade self-updates the CLI as part of an upgrade. To update it directly, rerun the installer — your deployment directories are untouched:

curl -fsSL https://beacon-mc.io/install.sh | sh

If an upgrade fails its health check

The CLI prints service-specific next checks. Tail the relevant log:

beacon logs minecraft     # first-boot / world issues
beacon logs admin-rpc     # RCON or Docker socket problems
beacon logs web           # dashboard boot
beacon status             # overall health probe

From the dashboard (one click)

From the CLI

Rolling back

Updating the CLI itself

If an upgrade fails its health check

On this page