Backups & Restore

A VPS can fail, and a bad mod or a careless command can wreck a world. Backups are the cheapest insurance you have. Beacon makes snapshots a first-class dashboard feature: deduplicated and incremental so a month of history costs a fraction of a month of full copies, restorable by facet, and copyable offsite.

Two kinds of snapshot

Open beacon admin → Snapshots. Every snapshot captures your server config — loader, Minecraft version, managed env, and the pinned mod list — as a small manifest. A snapshot is one of two kinds:

• Full — config plus the world. The world is archived save-safely: Beacon pauses autosave, flushes the world to disk, captures it, then re-enables autosave. Players stay connected.
• Config — config only. Instant, tiny, zero downtime — a reusable "server recipe" to roll settings/mods back to a known-good state.

Restore: world, config, or both

Restore is a scoped switch. On any snapshot, choose what to bring back:

• World + config — a full swap to that saved server.
• Config only — re-apply that loader/mods/settings recipe while the current map keeps playing.
• World only — roll the map back and leave config untouched.

Before it changes anything, Beacon takes a pre-restore safety snapshot of the current server (on by default) so the switch is reversible, then swaps the world atomically and restarts the container. You can warn players with a countdown first. Pin any snapshot to keep it as a permanent restore point that retention never prunes.

Deduplicated, incremental storage

Beacon stores world bytes in a restic repository under ./backups. Because a Minecraft world changes incrementally, each new snapshot stores and uploads only the chunks that changed — successive snapshots share the rest. A 10 GB world backed up nightly costs roughly the first snapshot plus small daily deltas, not 10 GB every night.

• Encryption is off by default and opt-in. The local repository sits on the same disk as the live (unencrypted) world, so encrypting it protects little — and a lost password makes every backup unrecoverable. Turn it on for offsite copies on storage you don't fully trust; the password is generated and shown once (save it), and you can retrieve it later from Storage.
• Retention is grandfather-father-son: keep the last N, plus the most recent hourly / daily / weekly / monthly snapshots. Older snapshots are thinned after each scheduled run; deleting a snapshot reclaims its unique chunks.
• Integrity can be verified against the repository.

What's captured — and what's skipped

A full snapshot captures your whole world (every dimension, player data, scoreboards, maps, structures) plus the config/ directory. It does not need the large, regenerable caches some mods write beside the world — those rebuild themselves from the live world, so backing them up just bloats every snapshot and every offsite upload.

Skip regenerable caches — on by default, under Snapshots → Snapshot contents — leaves those out:

• Distant Horizons LOD data (DistantHorizons.sqlite) — the level-of-detail databases Distant Horizons builds for far terrain. Routinely several gigabytes, and re-derived automatically as chunks load. Skipping it is the single biggest size win on a Distant Horizons server.
• session.lock — the one-byte world lock file the server recreates on every start.

Your real save data is never excluded: region files, entities, player data, scoreboards, maps, and raids are always captured — the skip list is matched by exact filename, so it can't touch them. After a restore, a skipped cache simply rebuilds the next time the world loads. Turn the toggle off to capture a byte-for-byte copy including the caches.

Schedule automatic snapshots

Turn on Automatic snapshots and pick a cadence — anywhere from every 15 minutes to weekly. Scheduled snapshots are full snapshots. A slot missed while the host was down fires once on the next boot — never a storm of catch-ups.

Copy backups offsite

A backup on the same disk as the world doesn't survive a host failure. Add an S3-compatible remote under Remote storage — AWS S3, Cloudflare R2, Backblaze B2, Wasabi, or any MinIO/Ceph endpoint — with your bucket and credentials, then turn on Offsite copy. It runs on its own cadence (hourly at the fastest, so a 15-minute local schedule doesn't hammer your bucket), ships only the new chunks, and prunes the remote to the same retention as the local repository. You can Test a remote's credentials from the dashboard; the secret key stays on the server and is never shown again after saving.

Where backups live on the host

Inside the deployment directory, two plain directories are bind-mounted on the host:

• ./data/ — the live Minecraft world and server files.
• ./backups/ — the restic repository (plus any legacy tar.gz snapshots and their .snapshot.json manifests).

Restoring after a disaster

On a fresh host: install the CLI, recreate the beacon (or restore the deployment directory and beacon up), restore ./backups/ (or point a remote at the new host), supply the repository password, then restore from Snapshots. Pin the same BEACON_VERSION and MC_VERSION you were running so the world loads cleanly.

In-game announcements

Optionally post a chat message when a snapshot starts and finishes (manual or scheduled), so players know about the brief pause during the world flush.