How to Self-Host BackupPC with Docker Compose

What Is BackupPC?

BackupPC is a centralized backup system that pulls backups from multiple machines over your network using rsync, SMB, or tar over SSH. It runs on a server and backs up client machines automatically on a schedule — no backup agent needed on clients (just SSH access for Linux/macOS or SMB shares for Windows). BackupPC includes a web UI for managing backups, browsing snapshots, and restoring files.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 2 GB of free RAM (minimum)
• Sufficient disk space for backup pool (depends on number of clients and data volume)
• SSH access to Linux/macOS clients, or SMB shares on Windows clients
• A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  backuppc:
    image: tiredofit/backuppc:6.0.4
    container_name: backuppc
    restart: unless-stopped
    ports:
      - "8080:80"           # Web UI
    volumes:
      - backuppc-config:/etc/backuppc            # BackupPC configuration
      - backuppc-data:/var/lib/backuppc          # Backup pool storage
      - backuppc-home:/home/backuppc             # SSH keys and user home
      - backuppc-logs:/var/log/backuppc          # Backup logs
    environment:
      TIMEZONE: UTC                              # Container timezone
      BACKUPPC_UUID: 1000                        # Host user ID for file permissions
      BACKUPPC_GUID: 1000                        # Host group ID for file permissions
    networks:
      - backup

networks:
  backup:
    driver: bridge

volumes:
  backuppc-config:
  backuppc-data:
  backuppc-home:
  backuppc-logs:

Start the stack:

docker compose up -d

Initial Setup

1. Open the web UI at http://your-server-ip:8080/BackupPC_Admin
2. Log in with the default credentials:
   • Username: backuppc
   • Password: backuppc (change this immediately)
3. Navigate to Edit Config → Server to review global settings
4. Set the backup schedule, retention policy, and notification email

Generate SSH Keys for Client Access

BackupPC needs SSH access to pull backups from Linux/macOS clients:

# Enter the container
docker exec -it backuppc bash

# Generate SSH key pair for the backuppc user
su - backuppc -c "ssh-keygen -t ed25519 -f /home/backuppc/.ssh/id_ed25519 -N ''"

# Display the public key — copy this to your client machines
cat /home/backuppc/.ssh/id_ed25519.pub

On each Linux client, add the public key to the root user’s authorized_keys:

# On the client machine
echo "PUBLIC_KEY_HERE" >> /root/.ssh/authorized_keys

Add a Client

1. In the web UI, go to Edit Hosts → Add Host
2. Enter the hostname or IP address of the client
3. Set the backup method:
   • rsync — recommended for Linux/macOS (fast, efficient)
   • smb — for Windows machines (no agent needed)
   • tar — fallback for any system with SSH
4. Configure the directories to back up under the host’s Xfer settings
5. Click Save and run a manual backup to test

Configuration

Backup Schedule

Edit the global schedule under Edit Config → Schedule:

Setting	Default	Recommended
Full backup period	7 days	7-14 days
Incremental period	1 day	1 day
Full backup retention	1	2-4
Incremental retention	6	14-30

Pool Deduplication

BackupPC uses a hardlink-based pool to deduplicate identical files across all clients. If 10 machines have the same 500 MB of OS files, BackupPC stores them once. This makes it extremely storage-efficient for homogeneous environments.

Email Notifications

Configure email alerts under Edit Config → Email:

EMailAdminUserName = [email protected]
EMailFromUserName = backuppc
EMailHeaders = MIME-Version: 1.0\nContent-Type: text/plain; charset="utf-8"

BackupPC sends alerts when backups fail, when a host hasn’t been backed up in too long, and when disk usage exceeds thresholds.

Reverse Proxy

To expose BackupPC behind a reverse proxy with SSL:

server {
    listen 443 ssl;
    server_name backups.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

See Reverse Proxy Setup for full configuration with Nginx Proxy Manager, Traefik, or Caddy.

Backup

BackupPC itself should be backed up. The critical data:

• /etc/backuppc/ — configuration files
• /var/lib/backuppc/ — the entire backup pool (this is the largest volume)
• /home/backuppc/.ssh/ — SSH keys for client access

Use Restic or BorgBackup to back up the BackupPC volumes to a separate location. See Backup Strategy.

Troubleshooting

Backup Fails with “Connection refused”

Symptom: Client backups fail with ssh: connect to host X port 22: Connection refused

Fix: Verify SSH is running on the client and the backuppc user’s public key is in the client’s authorized_keys. Test manually:

docker exec -it backuppc su - backuppc -c "ssh root@CLIENT_IP hostname"

“Pool is out of balance” Warning

Symptom: Web UI shows pool balance warnings

Fix: Run the pool cleanup:

docker exec -it backuppc /usr/bin/BackupPC_refCountUpdate -o

Web UI Returns 403

Symptom: Browser shows 403 Forbidden when accessing the web UI

Fix: Check that the BACKUPPC_UUID and BACKUPPC_GUID environment variables match your host user. Also verify the container is running:

docker logs backuppc

High Memory Usage

Symptom: BackupPC container uses 2+ GB RAM during backups

Fix: This is normal when backing up many clients simultaneously. Reduce MaxBackups (maximum concurrent backups) in the global config. Default is 4 — reduce to 2 for servers with limited RAM.

Resource Requirements

• RAM: 512 MB idle, 1-2 GB during active backups (depends on concurrent backup count)
• CPU: Low (backup I/O bound, not CPU bound)
• Disk: Depends entirely on backup volume. Budget 50-70% of total client data (deduplication helps significantly)

Verdict

BackupPC is the best option for centralized pull-based backups across a network of machines. The “agentless” model (SSH/SMB, no client software needed) makes it dead simple to add new machines. The pool deduplication saves serious storage when backing up similar systems.

The trade-off: BackupPC is an older project (4.4.0 released 2020) and development has slowed. For individual machine backups, use Restic or BorgBackup instead. BackupPC shines specifically when you need one server managing backups for 5+ machines over the network.

Related

• BackupPC vs Duplicati: Backup Tools Compared
• Best Self-Hosted Backup Solutions
• How to Self-Host Restic
• How to Self-Host BorgBackup
• How to Self-Host UrBackup
• UrBackup vs BackupPC
• Restic vs BorgBackup
• Replace Backblaze
• Backup Strategy
• Docker Compose Basics