AposaBackup

A Fabric mod for automated Minecraft world backups with local storage and S3 API(e.g. Cloudflare R2) cloud backup support. Works on both dedicated servers and single-player worlds.

Features

• Scheduled Automatic Backups — Configurable interval (default: 60 min)
• Manual Backups — /backup create with optional comments
• Shutdown Backups — Automatic backup when server stops
• Local Backup — Full ZIP archives with rotation policy (recent N + daily snapshots)
• Cloud Backup — Differential upload to Cloudflare R2 via S3 API with content-addressable deduplication
• Restore — Two-step restore with confirmation, auto-backup before restore
• Download — Export cloud backup as local ZIP
• In-game Notifications — Action bar messages for backup status
• Hot Configuration — All settings changeable via commands, no restart required

Installation

1. Download the mod JAR from releases
2. Place it in your server's or client's mods/ directory
3. Start the server — default config will be generated at config/aposabackup.json

Quick Start

# Create a manual backup
/backup create

# Create a backup with comment
/backup create before big build

# List local backups
/backup list

# Check backup system status
/backup status

Commands

All commands require OP level 3 (admin) permission.

Command	Description
/backup create [comment]	Create a local backup
/backup cloud	Create a cloud backup (differential upload)
/backup list [local|cloud]	List backups
/backup restore <id>	Prepare restore (requires confirmation)
/backup confirm	Confirm and execute restore
/backup download <id>	Download cloud backup as local ZIP
/backup delete <id> [local|cloud]	Delete a backup
/backup info <id>	Show backup details
/backup status	Show system status
/backup interval <min>	Set backup interval
/backup config <key> <value>	Change configuration
/backup config show	Show current configuration
/backup config reload	Reload from file

See github/docs/COMMANDS.md for full command reference.

Configuration

The config file is at config/aposabackup.json. All options can also be changed via /backup config.

{
  "version": 1,
  "local": {
    "enabled": true,
    "backupDir": "./backups",
    "format": "ZIP",
    "compressionLevel": 6,
    "intervalMinutes": 60,
    "recentBackups": 10,
    "dailyKeepDays": 7,
    "shutdownBackup": true,
    "excludePatterns": ["session.lock", "*.tmp"]
  },
  "cloud": {
    "enabled": false,
    "maxBackups": 30,
    "dailyKeepDays": 7,
    "uploadTimeoutSeconds": 300,
    "retryCount": 3,
    "r2": {
      "accountId": "",
      "accessKeyId": "",
      "secretAccessKey": "",
      "bucketName": "mc-server-backups",
      "region": "auto",
      "pathPrefix": "my-server/",
      "customEndpoint": ""
    }
  },
  "notification": {
    "enabled": true,
    "style": "ACTION_BAR"
  }
}

See github/docs/CONFIGURATION.md for detailed configuration reference.

Cloud Backup (e.g. Cloudflare R2)

AposaBackup supports differential cloud backups using Cloudflare R2's S3-compatible API.

How it works:

1. Only changed .mca region files are uploaded (SHA-256 content addressing)
2. Files are gzip-compressed and stored as content-addressed chunks
3. Each backup creates a manifest referencing the chunks
4. Unreferenced chunks are garbage-collected when old manifests are deleted

Setup: See github/docs/CLOUD_SETUP.md for step-by-step instructions.

Backup Rotation Policy

Local Backups

• Recent backups: Keeps the last N backups (default: 10)
• Daily snapshots: Automatically preserves the last backup of each day for N days (default: 7)

Cloud Backups

• Manifest retention: Keeps the last N manifests (default: 30)
• Daily snapshots: Preserves daily manifests for N days (default: 7)
• Garbage collection: Deletes unreferenced chunks after manifest cleanup

Restore Flow

/backup restore world_2026-06-22_14-00-00.zip
→ "About to restore backup. Current world will be backed up first."

/backup confirm
→ Creates pre-restore backup → Saves pending restore → Stops server

[Server restarts]
→ Detects pending restore → Decompresses backup → World restored