📦 BackItUp

A secure, flexible backup utility built with Bun

Glob patterns • tar.gz compression • Local + S3 storage • Docker volumes • Scheduled backups • Safe cleanup

✨ Features

🎯 Named Sources — Define backup sources with names and reference them in schedules
🔍 Glob Patterns — Include/exclude files using patterns (**/*.ts, !**/node_modules/**)
🐳 Docker Volumes — Backup Docker volumes with Docker Compose integration
☁️ Dual Storage — Store backups locally and/or in S3 (supports R2, MinIO, etc.)
⏰ Scheduled Backups — Cron-based scheduling with timezone support and independent retention policies
🛡️ Safe Cleanup — Multi-layer validation before any deletion (checksums, path verification)
✅ Integrity Verification — Verify backups exist and checksums match

🚀 Installation

Linux / macOS

# Quick install
curl -fsSL https://raw.githubusercontent.com/climactic/backitup/main/scripts/install.sh | bash
# Install specific version
curl -fsSL https://raw.githubusercontent.com/climactic/backitup/main/scripts/install.sh | bash -s -- --version v1.0.0
# Uninstall
curl -fsSL https://raw.githubusercontent.com/climactic/backitup/main/scripts/install.sh | bash -s -- --uninstall

Windows (PowerShell)

# Quick install
irm https://raw.githubusercontent.com/climactic/backitup/main/scripts/install.ps1 | iex
# Install specific version$env:BACKITUP_VERSION="v1.0.0"; irm https://raw.githubusercontent.com/climactic/backitup/main/scripts/install.ps1 | iex
# Uninstall$env:BACKITUP_ACTION="uninstall"; irm https://raw.githubusercontent.com/climactic/backitup/main/scripts/install.ps1 | iex

Docker

docker pull ghcr.io/climactic/backitup:latest

📥 Binaries for all platforms available on GitHub Releases

⚡ Quick Start

1. Create a config file (configuration reference):

backitup.config.yaml (click to expand)

version: "1.0"database:
path: "./data/backitup.db"sources:
app:
path: "/var/www/myapp"patterns:
- "**/*.ts"
- "**/*.js"
- "!**/node_modules/**"local:
enabled: truepath: "./backups"s3:
enabled: falsebucket: "my-backups"# region: "us-east-1"# endpoint: "http://localhost:9000" # For S3-compatible services# accessKeyId: "key" # Or use S3_ACCESS_KEY_ID env var# secretAccessKey: "secret" # Or use S3_SECRET_ACCESS_KEY env var# Optional: Set default timezone for all schedules# scheduler:# timezone: "America/New_York"schedules:
daily:
cron: "0 2 * * *"# Daily at 2 AM# timezone: "Europe/London" # Override global timezoneretention:
maxCount: 7# Keep max 7 backupsmaxDays: 14# Delete after 14 days

backitup.config.json (click to expand)

{
"version": "1.0",
"database": {
"path": "./data/backitup.db"
},
"sources": {
"app": {
"path": "/var/www/myapp",
"patterns": ["**/*.ts", "**/*.js", "!**/node_modules/**"]
}
},
"local": {
"enabled": true,
"path": "./backups"
},
"s3": {
"enabled": false,
"bucket": "my-backups"
},
"schedules": {
"daily": {
"cron": "0 2 * * *",
"retention": {
"maxCount": 7,
"maxDays": 14
}
}
}
}

2. Run:

backitup backup # Manual backup
backitup start # Start scheduler daemon
backitup list # List backups
backitup cleanup # Clean old backups
backitup verify --all # Verify integrity

📖 Commands

All commands support -c, --config <path> to specify a config file and -h, --help for detailed usage.

Command	Description	Docs
`backitup backup`	Create a backup	backup.md
`backitup start`	Start scheduler daemon	start.md
`backitup list`	List existing backups	list.md
`backitup cleanup`	Clean old backups	cleanup.md
`backitup verify`	Verify backup integrity	verify.md
`backitup export-db`	Export the database file	export-db.md

backitup start # Start scheduler daemon
backitup start -c /etc/backup.yaml
backitup backup # Create backup (interactive)
backitup backup -s daily # Create backup with schedule tag
backitup backup --dry-run # Preview what would be backed up
backitup backup --local-only # Skip S3 upload
backitup backup --volumes-only # Only backup Docker volumes
backitup cleanup # Clean old backups (with confirmation)
backitup cleanup -s daily # Clean only "daily" tagged backups
backitup cleanup --dry-run # Preview deletions
backitup cleanup --force # Skip confirmation
backitup list # List all backups
backitup list -s daily -n 10 # Filter by schedule, limit results
backitup list --format json # Output as JSON or CSV
backitup verify --all # Verify all backup checksums
backitup verify <backup-id># Verify specific backup
backitup verify --all --fix # Update DB for missing files
backitup export-db ./backup.db # Export database to file

⚙️ Inline Configuration

Override config file settings directly from the command line. Useful for quick backups, scripts, or CI/CD pipelines. See full inline config documentation.

Available Options

Category	Option	Description
Database	`--database <path>`	Database file path
Sources	`--source <path>`	Source path to backup (can be repeated)
	`--pattern <glob>`	Glob pattern for filtering (can be repeated)
Local Storage	`--local-path <path>`	Local storage path
	`--no-local`	Disable local storage
S3 Storage	`--s3-bucket <name>`	S3 bucket name
	`--s3-prefix <prefix>`	S3 key prefix
	`--s3-region <region>`	S3 region
	`--s3-endpoint <url>`	S3-compatible endpoint URL
	`--s3-access-key-id <key>`	S3 access key ID
	`--s3-secret-access-key <key>`	S3 secret access key
	`--no-s3`	Disable S3 storage
Retention	`--retention-count <n>`	Maximum backups to keep
	`--retention-days <n>`	Maximum days to retain backups
Archive	`--archive-prefix <str>`	Archive filename prefix
	`--compression <0-9>`	Compression level (default: 6)
Safety	`--verify-before-delete`	Verify checksums before cleanup
	`--no-verify-before-delete`	Skip checksum verification
Docker	`--docker`	Enable Docker volume backups
	`--no-docker`	Disable Docker volume backups
	`--docker-volume <name>`	Docker volume to backup (can be repeated)
	`--stop-containers`	Stop containers before volume backup
	`--no-stop-containers`	Don't stop containers (default)
	`--stop-timeout <seconds>`	Timeout for graceful stop (default: 30)
	`--restart-retries <n>`	Retry attempts for restart (default: 3)

Examples

# Quick backup with inline sources
backitup backup -s manual --source /var/www/app --local-path /backups
# Multiple sources with glob patterns
backitup backup -s manual --source /data --source /logs --pattern "**/*.log" --local-path /backups
# Backup directly to S3
backitup backup -s manual --source /app --s3-bucket my-backups --s3-region us-west-2 --no-local
# Backup with S3 credentials inline
backitup backup -s manual --source /data --s3-bucket my-bucket \
--s3-access-key-id AKIAIOSFODNN7EXAMPLE \
--s3-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# Start scheduler with inline overrides
backitup start --source /data --local-path /backups --s3-bucket my-bucket
# Override retention and compression
backitup backup -s manual --source /db --retention-count 5 --retention-days 7 --compression 9
# Backup Docker volumes inline
backitup backup -s manual --docker-volume postgres_data --docker-volume redis_data --local-path /backups

Inline options are merged with your config file. This allows you to use a base config and override specific settings as needed.

Config-Free Mode

You can run backitup without a config file by providing the required inline options:

Required options:

At least one source: --source or --docker-volume
At least one storage: --local-path or --s3-bucket

# Minimal backup without config file
backitup backup -s manual --source /data --local-path /backups
# Backup to S3 without config file
backitup backup -s manual --source /app --s3-bucket my-backups --s3-region us-west-2
# Docker volume backup without config file
backitup backup -s manual --docker-volume postgres_data --local-path /backups
# Full example with multiple options
backitup backup -s manual \
--source /var/www/app \
--pattern "**/*.js" --pattern "!**/node_modules/**" \
--local-path /backups \
--retention-count 5 \
--compression 9

If you run without a config file and don't provide sufficient options, backitup will tell you what's missing.

🐳 Docker Volume Backup

BackItUp can backup Docker volumes alongside your files. Each volume is backed up to a separate .tar.gz archive.

Configuration

version: "1.0"# ... other config ...docker:
enabled: true# Global container stop settings (optional)containerStop:
stopContainers: true # Stop containers before backupstopTimeout: 30# Seconds to wait for graceful stoprestartRetries: 3# Retry attempts if restart failsrestartRetryDelay: 1000# Milliseconds between retriesvolumes:
# Direct volume name
- name: postgres_data# Volume from Docker Compose service
- name: dbtype: composecomposePath: ./docker-compose.ymlprojectName: myapp # Optional, inferred from directory# Per-volume container stop override
- name: redis_datacontainerStop:
stopContainers: false # Override: don't stop for this volume

How It Works

BackItUp uses a temporary Alpine container to create the backup
The volume is mounted read-only to ensure data safety
If stopContainers is enabled:
- Containers using the volume are gracefully stopped before backup
- After backup completes, containers are automatically restarted
- Failed restarts are retried according to restartRetries setting
If a volume is in use by running containers without stopping, backup proceeds with a warning
Each volume produces a separate archive: backitup-volume-{name}-{schedule}-{timestamp}.tar.gz

Container Stop/Restart

For data consistency (especially with databases), you can stop containers before backing up their volumes:

# Stop containers before backup (CLI)
backitup backup -s daily --docker-volume postgres_data --stop-containers --local-path /backups
# With custom timeout and retries
backitup backup -s daily --docker-volume postgres_data \
--stop-containers --stop-timeout 60 --restart-retries 5 \
--local-path /backups

Important notes:

Containers with restart: always or restart: unless-stopped policies may auto-restart after being stopped. BackItUp detects this and logs a warning.
If a container fails to restart after all retries, the backup still succeeds but a warning is logged.
Per-volume settings override global settings, allowing fine-grained control.

Docker Compose Integration

When using type: compose, BackItUp resolves the actual Docker volume name:

# docker-compose.ymlservices:
db:
image: postgres:16volumes:
- db_data:/var/lib/postgresql/datavolumes:
db_data:

# backitup.config.yamldocker:
enabled: truevolumes:
- name: db_data # Direct: uses "db_data"
- name: db # Compose: resolves to "myapp_db_data"type: composecomposePath: ./docker-compose.yml

Restoring Volume Backups

# Extract the volume backup
tar -xzf backitup-volume-postgres_data-daily-2024-01-15T14-30-22-123Z.tar.gz -C /tmp/restore
# Create a new volume and restore
docker volume create postgres_data_restored
docker run --rm -v postgres_data_restored:/data -v /tmp/restore:/backup alpine \
sh -c "cp -a /backup/. /data/"

🐳 Running as a Service

Docker

The Docker image uses three volume mount points:

Mount Point	Purpose
`/config`	Config file (`backitup.config.yaml`) and database
`/data`	Source files to backup (or mount your own paths)
`/backups`	Local backup storage destination

docker run -d --name backitup \
-v ./config:/config \
-v ./data:/data:ro \
-v ./backups:/backups \
-e S3_ACCESS_KEY_ID=key \
-e S3_SECRET_ACCESS_KEY=secret \
ghcr.io/climactic/backitup:latest start

Your config file should reference these paths:

# /config/backitup.config.yamlversion: "1.0"database:
path: /config/backitup.dbsources:
app:
path: /datalocal:
enabled: truepath: /backups

To backup Docker volumes from within a container, mount the Docker socket:

docker run -d --name backitup \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ./config:/config \
-v ./data:/data:ro \
-v ./backups:/backups \
ghcr.io/climactic/backitup:latest start

You can also mount specific host paths instead of using /data:

docker run -d --name backitup \
-v ./config:/config \
-v /var/www/myapp:/myapp:ro \
-v /var/lib/postgres:/postgres:ro \
-v ./backups:/backups \
ghcr.io/climactic/backitup:latest start

Docker Compose

services:
backitup:
image: ghcr.io/climactic/backitup:latestcommand: startuser: root # Required for reading files with restrictive permissionsvolumes:
- ./config:/config # Config + database
- ./data:/data:ro # Source files (read-only)
- ./backups:/backups # Local backup destination
- /var/run/docker.sock:/var/run/docker.sock # For volume backupsenvironment:
- S3_ACCESS_KEY_ID=key
- S3_SECRET_ACCESS_KEY=secretrestart: unless-stopped

File Permissions

The Docker image runs as a non-root user (UID 1000) by default. If you're backing up files with restrictive permissions (e.g., SSH keys, database files), you have two options:

Tip: Always mount source data directories as read-only (:ro) to prevent accidental modifications during backup.

Option 1: Run as root (simplest)

services:
backitup:
image: ghcr.io/climactic/backitup:latestuser: root# ...

Option 2: Match the host user

If your files are owned by a specific user, run the container as that user:

services:
backitup:
image: ghcr.io/climactic/backitup:latestuser: "1000:1000"# Match the UID:GID of file owner# ...

One-time vs Scheduled Backups

Use command: start for the long-running scheduler daemon with restart: unless-stopped.

For one-time backups (e.g., triggered by cron or CI), use restart: on-failure to prevent the container from restarting indefinitely after a successful backup:

services:
backitup:
image: ghcr.io/climactic/backitup:latestcommand: backup -s manualuser: rootvolumes:
- ./config:/config
- ./data:/data:ro
- ./backups:/backupsrestart: on-failure # Don't restart after successful backup

systemd

# /etc/systemd/system/backitup.service[Unit]Description=backitup scheduler
After=network.target
[Service]Type=simple
ExecStart=/usr/local/bin/backitup start
Restart=always
[Install]WantedBy=multi-user.target

📚 Documentation

Document	Description
Configuration Reference	Complete config file reference
Inline Configuration	CLI options and config-free mode
Commands
backup	Create backups
start	Run scheduler daemon
list	List existing backups
cleanup	Remove old backups
verify	Verify backup integrity
export-db	Export the database file

🛠️ Development

bun install && bun run dev # Development with hot reload
bun test# Run tests
bun run build # Build standalone executable

💖 Support

If you find BackItUp useful, consider supporting its development:

Your support helps maintain and improve this project! ⭐

🏆 Title Sponsors

Title sponsors get their logo showcased here and in the project documentation. Become a title sponsor →

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github		.github
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Uh oh!

Uh oh!

Repository files navigation

📦 BackItUp

✨ Features

🚀 Installation

Linux / macOS

Windows (PowerShell)

Docker

⚡ Quick Start

📖 Commands

⚙️ Inline Configuration

Available Options

Examples

Config-Free Mode

🐳 Docker Volume Backup

Configuration

How It Works

Container Stop/Restart

Docker Compose Integration

Restoring Volume Backups

🐳 Running as a Service

Docker

Docker Compose

File Permissions

One-time vs Scheduled Backups

systemd

📚 Documentation

🛠️ Development

💖 Support

🏆 Title Sponsors

📜 License

About

Releases

Sponsor this project

Packages

Contributors

Languages

Uh oh!

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

📦 BackItUp

✨ Features

🚀 Installation

Linux / macOS

Windows (PowerShell)

Docker

⚡ Quick Start

📖 Commands

⚙️ Inline Configuration

Available Options

Examples

Config-Free Mode

🐳 Docker Volume Backup

Configuration

How It Works

Container Stop/Restart

Docker Compose Integration

Restoring Volume Backups

🐳 Running as a Service

Docker

Docker Compose

File Permissions

One-time vs Scheduled Backups

systemd

📚 Documentation

🛠️ Development

💖 Support

🏆 Title Sponsors

📜 License

About

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Contributors

Languages