Set up automatic Minecraft backups with itzg/mc-backup

Why this pattern is worth using

Backups become useful only when they are:

• automatic
• consistent
• tested

itzg/mc-backup is a strong default for Docker-based Minecraft servers because it is designed as a sidecar for itzg/minecraft-server. It coordinates backups over RCON, which means the server can flush and pause writes before the backup runs.

Recommended baseline architecture

Use one container for the Minecraft server and one sidecar container for backups.

The server data volume is mounted:

• read/write in the Minecraft container
• read-only in the backup container

The backup destination should be separate from the live world directory.

Compose example

services:
  mc:
    image: itzg/minecraft-server:latest
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      RCON_PASSWORD_FILE: /run/secrets/rcon_password
    volumes:
      - ./data:/data
    secrets:
      - rcon_password

  backup:
    image: itzg/mc-backup:latest
    restart: unless-stopped
    environment:
      RCON_HOST: mc
      RCON_PASSWORD_FILE: /run/secrets/rcon_password
      BACKUP_INTERVAL: 12h
      PRUNE_BACKUPS_DAYS: 7
    volumes:
      - ./data:/data:ro
      - ./backups:/backups
    secrets:
      - rcon_password

secrets:
  rcon_password:
    file: ./rcon_password

Before starting the stack, create rcon_password next to compose.yml and put a long random password in the file. Do not commit that file. Both containers must read the same secret: current itzg/minecraft-server builds generate a random RCON password by default, so relying on unrelated defaults will make backup coordination fail.

Why RCON matters here

The backup sidecar relies on RCON coordination for safe save handling. That is one reason not to disable RCON casually on the main container.

If your admin path is not working yet, fix RCON first before you rely on automated backups for real recovery.

Safe defaults to start with

These defaults are pragmatic:

• BACKUP_INTERVAL: 12h
• PRUNE_BACKUPS_DAYS: 7
• local backup directory mounted on the host

That gives you:

• multiple restore points per week
• limited storage growth
• easy visibility into whether backups are being created

For more control, the image also supports cron-based scheduling and alternative backup methods.

Validate the setup immediately

Bring up the stack:

docker compose up -d

Then inspect the backup container logs:

docker compose logs -f backup

You want to confirm:

• a backup job actually runs
• backup archives appear under ./backups
• no RCON coordination errors occur

For an on-demand backup, execute:

docker compose exec backup backup now

Use the Compose service name backup; do not assume that the generated container name is literally backup. Confirm a new archive and a successful exit in the logs before treating the job as working.

Retention and storage notes

Avoid keeping everything forever by accident. Retention should match the value of the world and your storage budget.

A simple starting model:

• backups every 12 hours
• keep 7 days locally
• keep a second offsite copy if the server matters

Do not assume that infrastructure snapshots are a complete replacement. On Hetzner, attached volumes are not included in Cloud Backups and Snapshots, so treat infrastructure snapshots only as a secondary layer.

Common mistakes

FAQ

Should /data be mounted read-only in the backup container?

Yes. That is the safer default because the backup sidecar does not need write access to the live world files.

Is a local backup directory enough?

It is better than no backup, but not enough for high-value servers. Local-only backups do not protect you from full host loss.

Next steps

• Find cloud storage and Discord notification examples in the Backup Guide.
• Rehearse the full recovery path with the Docker restore runbook.
• If you host on Hetzner, understand why infrastructure snapshots do not include attached Volumes.
• If safe stop commands or backup coordination still fail, verify your RCON path before trusting the backup job in production.