# Borg Backup + Borgmatic + Vorta

> Deduplicating backup with automation and GUI client.

- Category: Storage & Backup
- Difficulty: intermediate
- Components: borg-server, borgmatic
- Tags: borg, backup, deduplication, encryption, borgmatic
- Source: https://docker.recipes/storage/borg-backup-server

## 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.

## 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

## Use cases

- Multi-server infrastructure backup with centralized Borg repository and automated retention policies
- Development workstation protection with Vorta GUI for ad-hoc backups and project restoration
- Home media server backup with deduplication for large file collections and version histories
- Database backup automation using Borgmatic pre-hooks for consistent dump creation
- Remote site backup replication over SSH with encrypted transport and storage
- Continuous integration artifact archival with automated cleanup of old build outputs
- Personal 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

## docker-compose.yml

```yaml
services:
  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:
    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

volumes:
  borg-repo:
  borg-cache:
  borgmatic-config:

networks:
  borg-network:
    driver: bridge
```

## .env

```bash
# Borg Backup
BORG_PASSPHRASE=your-secure-passphrase

# Change /path/to/source to your data directory
# Configure borgmatic via /etc/borgmatic.d/config.yaml
```

## Usage notes

- Initialize: borgmatic init
- Create backup: borgmatic create
- Vorta for desktop GUI
- Deduplication reduces space
- AES-256-CTR encryption

## 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

