Set up automatic Minecraft backups with itzg/mc-backup

How the backup container works

itzg/mc-backup runs alongside itzg/minecraft-server. It coordinates backups over RCON, which means the server can flush and pause writes before the backup runs.

Container and volume layout

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

This example uses:

• 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

Set a retention period so old archives do not fill the backup disk.

A simple starting model:

• backups every 12 hours
• keep 7 days locally
• keep a second copy outside the server

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

Next steps

• Find cloud storage and Discord notification examples in the Backup Guide.
• If safe stop commands or backup coordination still fail, verify your RCON path before trusting the backup job in production.