docker.recipes

Borg Backup + Borgmatic + Vorta

intermediate

Deduplicating backup with automation and GUI client.

Overview

Borg Backup is a deduplicating backup program that creates space-efficient, encrypted archives while maintaining fast incremental backups through content-defined chunking and rolling hash algorithms. Originally developed as an improved fork of Attic, Borg has become the de facto standard for efficient backup solutions, offering AES-256-CTR encryption and cross-platform compatibility. The borg-server component provides repository access over SSH or local filesystem interfaces, enabling centralized backup storage with proper authentication and access control. This stack combines Borg's core backup engine with Borgmatic's automation layer and Vorta's desktop client interface to create a complete backup ecosystem. Borgmatic handles scheduling, retention policies, and notification workflows through YAML configuration files, while Vorta provides a Qt-based GUI for backup management, repository browsing, and restore operations. The containerized architecture isolates backup operations from host system dependencies while maintaining access to source data and persistent repository storage. System administrators managing multiple servers, developers protecting project data, and home lab enthusiasts requiring reliable backup automation will benefit from this integrated approach. The combination eliminates manual backup scheduling through Borgmatic's cron integration while providing user-friendly access via Vorta's desktop interface, making enterprise-grade deduplication and encryption accessible to both technical and non-technical users.

Key Features

  • Content-defined chunking with rolling hash deduplication reduces storage requirements by 50-80%
  • AES-256-CTR encryption with HMAC-SHA256 authentication protects data at rest and in transit
  • Borgmatic YAML configuration enables declarative backup policies with retention rules and pre/post-hooks
  • Incremental backup processing only transfers changed chunks since last archive creation
  • Cross-repository deduplication when multiple repositories share common data patterns
  • Vorta desktop integration provides repository browsing, archive mounting, and graphical restore workflows
  • Backup verification through repository check operations and archive consistency validation
  • Compression algorithms including LZ4, ZLIB, LZMA, and ZSTD with configurable compression levels

Common Use Cases

  • 1Multi-server infrastructure backup with centralized Borg repository and automated retention policies
  • 2Development workstation protection with Vorta GUI for ad-hoc backups and project restoration
  • 3Home media server backup with deduplication for large file collections and version histories
  • 4Database backup automation using Borgmatic pre-hooks for consistent dump creation
  • 5Remote site backup replication over SSH with encrypted transport and storage
  • 6Continuous integration artifact archival with automated cleanup of old build outputs
  • 7Personal document backup with Vorta scheduling and encrypted cloud storage mounting

Prerequisites

  • Docker Engine 20.10+ with Docker Compose v2 for container orchestration support
  • Minimum 512MB RAM per container plus repository cache storage requirements
  • Source data directories with appropriate read permissions for container access
  • BORG_PASSPHRASE environment variable configured for repository encryption key
  • SSH key configuration if using remote repository access over network connections
  • Understanding of Borg archive concepts and Borgmatic YAML configuration structure

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  borg-server: 
3    image: ghcr.io/borgmatic-collective/borgmatic:latest
4    environment: 
5      - BORG_PASSPHRASE=${BORG_PASSPHRASE}
6    volumes: 
7      - borg-repo:/borg/repo
8      - borg-cache:/root/.cache/borg
9      - borgmatic-config:/etc/borgmatic.d
10      - /path/to/source:/source:ro
11    networks: 
12      - borg-network
13    restart: unless-stopped
14
15  borgmatic: 
16    image: ghcr.io/borgmatic-collective/borgmatic:latest
17    environment: 
18      - BORG_PASSPHRASE=${BORG_PASSPHRASE}
19      - BORG_REPO=/borg/repo
20    volumes: 
21      - borg-repo:/borg/repo
22      - borg-cache:/root/.cache/borg
23      - borgmatic-config:/etc/borgmatic.d
24      - /path/to/source:/source:ro
25    command: cron
26    networks: 
27      - borg-network
28    restart: unless-stopped
29
30volumes: 
31  borg-repo: 
32  borg-cache: 
33  borgmatic-config: 
34
35networks: 
36  borg-network: 
37    driver: bridge

.env Template

.env
1# Borg Backup
2BORG_PASSPHRASE=your-secure-passphrase
3
4# Change /path/to/source to your data directory
5# Configure borgmatic via /etc/borgmatic.d/config.yaml

Usage Notes

  1. 1Initialize: borgmatic init
  2. 2Create backup: borgmatic create
  3. 3Vorta for desktop GUI
  4. 4Deduplication reduces space
  5. 5AES-256-CTR encryption

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

borg-server
borg-server:
  image: ghcr.io/borgmatic-collective/borgmatic:latest
  environment:
    - BORG_PASSPHRASE=${BORG_PASSPHRASE}
  volumes:
    - borg-repo:/borg/repo
    - borg-cache:/root/.cache/borg
    - borgmatic-config:/etc/borgmatic.d
    - /path/to/source:/source:ro
  networks:
    - borg-network
  restart: unless-stopped
borgmatic
borgmatic:
  image: ghcr.io/borgmatic-collective/borgmatic:latest
  environment:
    - BORG_PASSPHRASE=${BORG_PASSPHRASE}
    - BORG_REPO=/borg/repo
  volumes:
    - borg-repo:/borg/repo
    - borg-cache:/root/.cache/borg
    - borgmatic-config:/etc/borgmatic.d
    - /path/to/source:/source:ro
  command: cron
  networks:
    - borg-network
  restart: unless-stopped

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  borg-server:
5    image: ghcr.io/borgmatic-collective/borgmatic:latest
6    environment:
7      - BORG_PASSPHRASE=${BORG_PASSPHRASE}
8    volumes:
9      - borg-repo:/borg/repo
10      - borg-cache:/root/.cache/borg
11      - borgmatic-config:/etc/borgmatic.d
12      - /path/to/source:/source:ro
13    networks:
14      - borg-network
15    restart: unless-stopped
16
17  borgmatic:
18    image: ghcr.io/borgmatic-collective/borgmatic:latest
19    environment:
20      - BORG_PASSPHRASE=${BORG_PASSPHRASE}
21      - BORG_REPO=/borg/repo
22    volumes:
23      - borg-repo:/borg/repo
24      - borg-cache:/root/.cache/borg
25      - borgmatic-config:/etc/borgmatic.d
26      - /path/to/source:/source:ro
27    command: cron
28    networks:
29      - borg-network
30    restart: unless-stopped
31
32volumes:
33  borg-repo:
34  borg-cache:
35  borgmatic-config:
36
37networks:
38  borg-network:
39    driver: bridge
40EOF
41
42# 2. Create the .env file
43cat > .env << 'EOF'
44# Borg Backup
45BORG_PASSPHRASE=your-secure-passphrase
46
47# Change /path/to/source to your data directory
48# Configure borgmatic via /etc/borgmatic.d/config.yaml
49EOF
50
51# 3. Start the services
52docker compose up -d
53
54# 4. View logs
55docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/borg-backup-server/run | bash

Troubleshooting

  • Repository does not exist error: Run 'docker-compose exec borgmatic borgmatic init --encryption repokey-blake2' to initialize new repository
  • Permission denied accessing source files: Verify source volume mount permissions and consider using user mapping in container configuration
  • Borg cache corruption during backup: Clear cache volume and run 'borg delete --cache-only' to rebuild cache from repository metadata
  • Borgmatic configuration not found: Ensure borgmatic-config volume contains valid config.yaml file with repository and source_directories defined
  • Passphrase authentication failure: Verify BORG_PASSPHRASE environment variable matches repository encryption key
  • Vorta connection refused: Check that borg-server container is running and SSH daemon is properly configured for client access

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

borg-serverborgmatic

Tags

#borg#backup#deduplication#encryption#borgmatic

Category

Storage & Backup

Related Recipes

Ad Space