Automated Backups

The Lumo Server includes a comprehensive automated backup system with compression, retention policies, and multiple destination support.

Features

Automated Daily Backups: Runs on configurable schedule (default: every 24 hours)
Compression: gzip, bzip2, or xz compression
Retention Policy: Keep 7 daily + 4 weekly backups by default
Multiple Destinations: Local storage, S3-compatible, rclone
Safe Backups: Automatically disables world saving during backup
Discord Notifications: Optional notifications for backup events
Easy Restore: Simple restore script included

Quick Start

Enable Backups

Backups are enabled by default. Configure with volume mount:

docker run \
  -v minecraft_data:/data \
  -v minecraft_backups:/backups \
  ghcr.io/lucasilverentand/lumo-server:latest

Backups will be stored in the /backups volume.

Manual Backup

Trigger a manual backup:

docker exec <container> python3 /backup.py

Restore from Backup

Stop the server:
Terminal window
```
docker stop <container>
```

List available backups:

docker run --rm -v minecraft_backups:/backups ghcr.io/lucasilverentand/lumo-server:latest ls -lh /backups

Restore from backup:

docker run --rm \
  -v minecraft_data:/data \
  -v minecraft_backups:/backups \
  ghcr.io/lucasilverentand/lumo-server:latest /restore.sh <backup-filename>

Start the server:
Terminal window
```
docker start <container>
```

Configuration

Configure backups via environment variables:

Variable	Default	Description
`BACKUP_ENABLED`	`true`	Enable/disable automated backups
`BACKUP_INTERVAL`	`86400`	Backup interval in seconds (24h)
`BACKUP_DIR`	`/backups`	Directory to store backups
`BACKUP_RETENTION_DAYS`	`7`	Keep backups from last N days
`BACKUP_RETENTION_WEEKS`	`4`	Keep one weekly backup for N weeks
`BACKUP_COMPRESSION`	`gz`	Compression: `gz`, `bz2`, or `xz`

Compression Options

gz (gzip): Fast compression, moderate size (recommended)
bz2 (bzip2): Slower compression, smaller size
xz: Slowest compression, smallest size

Example: 12-hour backups with 14-day retention

docker run \
  -e BACKUP_INTERVAL=43200 \
  -e BACKUP_RETENTION_DAYS=14 \
  -e BACKUP_RETENTION_WEEKS=8 \
  -v minecraft_backups:/backups \
  ghcr.io/lucasilverentand/lumo-server:latest

S3-Compatible Storage

Upload backups to S3, MinIO, Backblaze B2, or other S3-compatible services.

Configuration

Variable	Default	Description
`S3_ENABLED`	`false`	Enable S3 uploads
`S3_BUCKET`	`""`	S3 bucket name
`S3_PREFIX`	`minecraft-backups`	S3 object prefix/folder
`S3_ENDPOINT`	`""`	Custom endpoint (for MinIO, B2, etc.)

AWS S3 Example

docker run \
  -e S3_ENABLED=true \
  -e S3_BUCKET=my-minecraft-backups \
  -e AWS_ACCESS_KEY_ID=AKIA... \
  -e AWS_SECRET_ACCESS_KEY=... \
  -e AWS_DEFAULT_REGION=us-east-1 \
  ghcr.io/lucasilverentand/lumo-server:latest

MinIO Example

docker run \
  -e S3_ENABLED=true \
  -e S3_BUCKET=minecraft \
  -e S3_ENDPOINT=https://minio.example.com \
  -e AWS_ACCESS_KEY_ID=minioadmin \
  -e AWS_SECRET_ACCESS_KEY=minioadmin \
  ghcr.io/lucasilverentand/lumo-server:latest

Backblaze B2 Example

docker run \
  -e S3_ENABLED=true \
  -e S3_BUCKET=my-bucket \
  -e S3_ENDPOINT=https://s3.us-west-002.backblazeb2.com \
  -e AWS_ACCESS_KEY_ID=<key_id> \
  -e AWS_SECRET_ACCESS_KEY=<application_key> \
  ghcr.io/lucasilverentand/lumo-server:latest

Rclone Support

Use rclone to backup to 50+ cloud storage providers.

Setup

Configure rclone on your host:
Terminal window
```
rclone config
```

Mount rclone config into container:

docker run \
  -e RCLONE_ENABLED=true \
  -e RCLONE_DEST="remote:bucket/minecraft" \
  -v ~/.config/rclone:/root/.config/rclone:ro \
  ghcr.io/lucasilverentand/lumo-server:latest

Supported Destinations

Rclone supports 50+ providers including:

Google Drive
Dropbox
OneDrive
SFTP
FTP
WebDAV
And many more

See rclone.org for full list.

Discord Notifications

Receive backup status notifications in Discord.

Setup

Create Discord webhook:
- Server Settings → Integrations → Webhooks → New Webhook
- Copy webhook URL

Configure:

docker run \
  -e DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..." \
  ghcr.io/lucasilverentand/lumo-server:latest

Notification Types

✅ Backup Success: Backup completed with filename and size
❌ Backup Failed: Backup failed with error message

Backup Contents

The backup includes:

All world data (overworld, nether, end)
Player data (inventories, locations, stats)
Plugin configurations
Plugin data (economy, permissions, etc.)
Server properties

The backup excludes:

Log files
Temporary files
Cache directories
Session locks

Restore Process

Full Restore

Complete server restoration from backup:

Stop the server (REQUIRED):
Terminal window
```
docker stop minecraft-server
```

Run restore script:

docker run --rm -it \
  -v minecraft_data:/data \
  -v minecraft_backups:/backups \
  ghcr.io/lucasilverentand/lumo-server:latest /restore.sh minecraft-backup-20251219_120000.tar.gz

Confirm restore:
- Script will ask for confirmation
- Creates safety backup of current data
- Extracts backup archive
- Fixes permissions
Start server:
Terminal window
```
docker start minecraft-server
```

Partial Restore

Restore specific files or worlds:

Extract backup to temporary location:

mkdir /tmp/backup-extract
tar -xzf minecraft-backup-20251219_120000.tar.gz -C /tmp/backup-extract

Copy specific files:

# Restore just one world
docker cp /tmp/backup-extract/data/world minecraft-server:/data/

# Restore player data
docker cp /tmp/backup-extract/data/world/playerdata minecraft-server:/data/world/

Fix permissions and restart:

docker exec minecraft-server chown -R minecraft:minecraft /data
docker restart minecraft-server

Monitoring Backups

Check Backup Logs

docker logs minecraft-server | grep BACKUP

List Backups

docker run --rm -v minecraft_backups:/backups ghcr.io/lucasilverentand/lumo-server:latest ls -lh /backups

Check Backup Size

docker run --rm -v minecraft_backups:/backups ghcr.io/lucasilverentand/lumo-server:latest du -sh /backups

Verify Backup Contents

docker run --rm -v minecraft_backups:/backups ghcr.io/lucasilverentand/lumo-server:latest \
  tar -tzf /backups/minecraft-backup-20251219_120000.tar.gz | head -20

Retention Policy

The backup system automatically manages old backups:

Daily Backups

Keeps all backups from the last BACKUP_RETENTION_DAYS days
Default: 7 days

Weekly Backups

After daily retention expires, keeps one backup per week
Keeps weekly backups for BACKUP_RETENTION_WEEKS weeks
Default: 4 weeks

Example Timeline

With defaults (7 days + 4 weeks):

Day 1-7: All daily backups kept (7 backups)
Week 2-5: One backup per week (4 backups)
Older: Deleted automatically

Total: ~11 backups at any time

Custom Retention

# Keep 14 days + 8 weeks
docker run \
  -e BACKUP_RETENTION_DAYS=14 \
  -e BACKUP_RETENTION_WEEKS=8 \
  ghcr.io/lucasilverentand/lumo-server:latest

Troubleshooting

Backups not running

Check logs:

docker logs minecraft-server | grep BACKUP

Verify backup is enabled:

docker inspect minecraft-server | grep BACKUP_ENABLED

Backup failed - disk space

Check available space:

df -h /var/lib/docker/volumes/

Cleanup old backups manually:

docker run --rm -v minecraft_backups:/backups ghcr.io/lucasilverentand/lumo-server:latest \
  find /backups -name "*.tar.gz" -mtime +30 -delete

Restore failed - permissions

Fix permissions:

docker exec minecraft-server chown -R minecraft:minecraft /data

S3 upload failed

Verify credentials:

docker exec minecraft-server aws s3 ls s3://your-bucket

Check S3 endpoint:

docker logs minecraft-server | grep "S3 upload"

Backup too large

Use better compression:

# Use xz instead of gz
docker run -e BACKUP_COMPRESSION=xz ghcr.io/lucasilverentand/lumo-server:latest

Exclude more files (edit /backup.py excludes list)

Best Practices

1. Test Restores Regularly

Test restore process monthly to ensure backups are valid:

# Create test container
docker run -d --name mc-test \
  -v minecraft_test_data:/data \
  -v minecraft_backups:/backups \
  ghcr.io/lucasilverentand/lumo-server:latest /restore.sh latest-backup.tar.gz

# Verify it starts
docker logs mc-test

# Cleanup
docker rm -f mc-test
docker volume rm minecraft_test_data

2. Use Remote Backups

Always use S3 or rclone for off-site backups. Local-only backups don’t protect against hardware failure.

3. Monitor Backup Size

Track backup sizes over time:

docker run --rm -v minecraft_backups:/backups ghcr.io/lucasilverentand/lumo-server:latest \
  find /backups -name "*.tar.gz" -printf "%TY-%Tm-%Td %p %s\n"

4. Backup Before Updates

Before updating Minecraft version or plugins:

# Force immediate backup
docker exec minecraft-server python3 /backup.py

5. Document Backup Strategy

Keep a note of:

Where backups are stored
S3/rclone credentials
Retention policy
Last successful restore test

Advanced Usage

Custom Backup Schedule

Use external cron to trigger backups:

# Disable internal backup daemon
docker run -e BACKUP_ENABLED=false ghcr.io/lucasilverentand/lumo-server:latest

# Add cron job on host
0 2 * * * docker exec minecraft-server python3 /backup.py

Backup to Multiple Destinations

Enable both S3 and rclone:

docker run \
  -e S3_ENABLED=true \
  -e S3_BUCKET=primary-backups \
  -e RCLONE_ENABLED=true \
  -e RCLONE_DEST="secondary:backups" \
  ghcr.io/lucasilverentand/lumo-server:latest

Backup Hooks

Run custom scripts before/after backups:

# Create pre-backup script
docker exec minecraft-server sh -c 'cat > /pre-backup.sh << EOF
#!/bin/bash
# Your custom pre-backup tasks
echo "Running pre-backup tasks..."
EOF'

# Modify backup.py to call hooks

Security Considerations

Backup Encryption

Backups are not encrypted by default. For sensitive data:

# Encrypt backups with GPG
docker run --rm -v minecraft_backups:/backups ghcr.io/lucasilverentand/lumo-server:latest \
  gpg --symmetric --cipher-algo AES256 /backups/minecraft-backup-*.tar.gz

Access Control

Use IAM roles for S3 (avoid hardcoded credentials)
Restrict S3 bucket access with bucket policies
Use rclone encryption for cloud storage

Secure Deletion

When removing old backups:

# Secure deletion
docker run --rm -v minecraft_backups:/backups ghcr.io/lucasilverentand/lumo-server:latest \
  shred -u /backups/old-backup.tar.gz

Next Steps

Environment Variables - Full backup configuration reference
Docker Compose - Backup configuration in Compose
Troubleshooting - Common issues