Docker Hooks

Borg UI can run pre-backup and post-backup scripts. If the Docker CLI is configured inside the Borg UI container, those scripts can stop, start, inspect, or restart containers.

Use this only when you need consistent backups of stateful containers.

Enable Docker Access

Use one of these patterns.

Direct Socket Mount

Add the Docker socket to the Borg UI container:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:rw

This gives the Borg UI container control over the host Docker daemon. Treat it as host-level access.

Docker Socket Proxy

To avoid mounting the Docker socket into the Borg UI app container, run a Docker socket proxy such as Tecnativa/docker-socket-proxy on the same Docker network and point the app container's Docker CLI at it:

services:
  app:
    environment:
      - DOCKER_HOST=tcp://docker-socket-proxy:2375
    # Remove the /var/run/docker.sock mount from the app service when using this.

  docker-socket-proxy:
    image: ghcr.io/tecnativa/docker-socket-proxy:0.4.2
    profiles: ["docker-socket-proxy"]
    restart: unless-stopped
    privileged: true
    environment:
      - CONTAINERS=1
      - INFO=1
      - POST=1
      - ALLOW_START=1
      - ALLOW_STOP=1
      - ALLOW_RESTARTS=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Start that profile with:

docker compose --profile docker-socket-proxy up -d

The proxy container still mounts the host socket, but Borg UI talks to the proxy over DOCKER_HOST=tcp://docker-socket-proxy:2375 instead of mounting the socket directly. Keep the proxy on an internal Docker network only. Do not publish port 2375 to the host or internet.

Docker CLI

The socket or socket proxy exposes the Docker daemon, but scripts still need the docker command inside the Borg UI container. Install docker.io from:

Settings > System > Packages

You can also use a custom image that includes the Docker CLI.

Typical Flow

1. Create a script in the script library.
2. Attach it to a repository or Backup Plan as a pre-backup or post-backup hook.
3. Set execution order if multiple scripts run.
4. Test the script before relying on a scheduled backup.

Backup Plan hooks use saved scripts from the script library. Add one or more scripts to the pre-backup or post-backup chain, then choose the pre-backup failure behavior or the post-backup run condition for each script.

Common use:

• pre-backup: stop a database container
• backup: run Borg
• post-backup: start the database container

Runtime Environment

Borg UI injects these variables when scripts run:

Variable	Meaning
BORG_UI_HOOK_TYPE	pre-backup or post-backup
BORG_UI_BACKUP_STATUS	success, failure, or warning for post-backup hooks
BORG_UI_REPOSITORY_ID	Repository ID
BORG_UI_REPOSITORY_NAME	Repository name
BORG_UI_REPOSITORY_PATH	Repository path
BORG_UI_JOB_ID	Backup job ID, when available
BORG_UI_REMOTE_HOST	Remote source host for script library execution and script tests
BORG_UI_REMOTE_PORT	Remote source SSH port for script library execution and script tests
BORG_UI_REMOTE_USERNAME	Remote source username for script library execution and script tests
BORG_UI_SOURCE_HOST	Remote source host for legacy inline repository hooks
BORG_UI_SOURCE_PORT	Remote source SSH port for legacy inline repository hooks
BORG_UI_SOURCE_USERNAME	Remote source username for legacy inline repository hooks

Variables starting with BORG_UI_ are reserved by Borg UI and are not treated as script parameters.

Example Pre-Backup Script

#!/usr/bin/env bash
set -euo pipefail

container="${CONTAINER_NAME:-postgres}"

if docker ps --format '{{.Names}}' | grep -qx "$container"; then
  docker stop "$container"
fi

Example Post-Backup Script

#!/usr/bin/env bash
set -euo pipefail

container="${CONTAINER_NAME:-postgres}"

if docker ps -a --format '{{.Names}}' | grep -qx "$container"; then
  docker start "$container"
fi

Safer Pattern

Prefer application-native dump commands when possible.

For databases, a pre-backup script that writes a dump file is often safer than stopping the live container:

#!/usr/bin/env bash
set -euo pipefail

mkdir -p /local/db-dumps
docker exec postgres pg_dumpall -U postgres > /local/db-dumps/postgres.sql

Then back up /local/db-dumps.

Security Rules

• Do not mount the Docker socket unless hooks need it.
• Prefer a Docker socket proxy when hooks only need a limited Docker API surface.
• If you use a socket proxy, expose only the API sections required by your scripts and keep port 2375 private to the Docker network.
• Do not run unreviewed scripts.
• Use repository-specific parameters for container names.
• Keep scripts idempotent.
• Make post-backup cleanup run on failure.

Troubleshooting

docker: command not found

Install docker.io from Settings > System > Packages, or use a custom image that includes the Docker CLI.

Container stays stopped after a backup failure

Use a post-backup hook that runs on failure as well as success if the pre-backup hook stops a service.

Related

• Troubleshooting
• Script Parameters
• Installation
• Security