Portabase Logo
Portabase AgentDatabases

Docker Volume

Configuration for Docker Volume backups.

Add this volume from the dashboard

Since Dashboard 1.29.0 and Agent 1.19.0, you can add this volume directly from the dashboard (Add database on the agent page). See Adding a Database. The settings described below also apply to the dashboard form, and the Docker socket must still be mounted in the agent container.

The docker-volume type lets the agent back up a Docker named volume directly, without going through a database driver. It is useful for engines with no dedicated dump tool, or for protecting any container's data volume as-is.

Backup and restore are performed on the fly, hot, without stopping the target container.

This provider requires the agent to have access to the Docker socket. You must mount /var/run/docker.sock:/var/run/docker.sock on the agent container, otherwise it cannot inspect or archive the volume.

Configuration

When running portabase agent db add, select docker-volume as the database type.

Specific parameters asked:

  • Volume Name: The exact name of the Docker volume to back up (e.g., databases_sqlite-data).
  • Container Name: (Optional, but recommended) The name of the container currently using the volume. Provide it so the agent can automatically restart that container after a restore.

Docker Compose Example

The agent needs access to the Docker socket to inspect and archive volumes. Mount it alongside your regular agent configuration.

docker-compose.yml
services:
  agent:
    image: portabase/agent:latest
    volumes:
      - ./databases.json:/config/config.json
      # Required: gives the agent access to the Docker daemon
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      TZ: "Europe/Paris"
      EDGE_KEY: "..."
    networks:
      - portabase

networks:
  portabase:
    name: portabase_network
    external: true

Without the Docker socket mounted, the agent cannot resolve or archive the volume and the backup job will fail.

Podman

The agent works with Podman through its Docker-compatible API socket. Mount the Podman socket in place of the Docker one. With rootless Podman, the socket belongs to the user running the containers (/run/user/<uid>/podman/podman.sock). Enable it first with systemctl --user enable --now podman.socket.

docker-compose.yml
services:
  agent:
    image: portabase/agent:latest
    volumes:
      - ./databases.json:/config/config.json
      # Rootless Podman socket of the user owning the volumes
      - /run/user/1000/podman/podman.sock:/var/run/docker.sock

Since Agent 1.26.2, an agent running in the same Podman as the volumes needs nothing else, backups keep file ownership, and restores accept backups taken under Docker or Podman.

Before Agent 1.26.2, restoring a backup taken under Podman empties the volume instead of restoring it. Upgrade the agent before restoring. Backups taken under Podman by an older agent also lost file ownership (files come back owned by root): take a new backup after upgrading.

Agent and volumes on different engines

The agent creates a short-lived helper container from its own image, looked up on the engine behind the mounted socket. If the agent itself runs on another engine (for example the agent on Docker and the volumes in rootless Podman), that engine does not know the agent container and the backup fails with Failed to inspect self container.

Set PORTABASE_HELPER_IMAGE to an image already present on the engine behind the socket. It must contain sh, sleep and tar and have no ENTRYPOINT, or only one that runs the command it is given: restores, and backups under Podman, start the helper with a sh -c command. For example docker.io/library/alpine:3:

docker-compose.yml
services:
  agent:
    environment:
      PORTABASE_HELPER_IMAGE: "docker.io/library/alpine:3"

Pull it first on that engine (podman pull docker.io/library/alpine:3 as the Podman user). The agent never pulls it, so this keeps working offline once the image is present.

Temporary storage and disk space

During a docker-volume backup, the agent builds the backup archive in a temporary directory inside the agent container, using the system temp location, /tmp by default.

If /tmp sits on a cramped root filesystem, backing up a large volume fails with:

No space left on device

The temporary archive needs roughly the size of the volume being backed up. A 20 GB volume needs about 20 GB free at the temp location, not just at the destination.

Redirect the temp directory

The agent honors the standard TMPDIR environment variable. Point it at a directory backed by a bigger disk, and mount host storage there:

docker-compose.yml
services:
  agent:
    image: portabase/agent:latest
    volumes:
      - ./databases.json:/config/config.json
      - /var/run/docker.sock:/var/run/docker.sock
      # Host dir with enough free space
      - /mnt/bigdisk:/scratch
    environment:
      TZ: "Europe/Paris"
      EDGE_KEY: "..."
      # Tell the agent to build temp archives here instead of /tmp
      TMPDIR: /scratch

Use a host path (/mnt/bigdisk) with more free space than the backup size. The temp archive is built there instead of the cramped root filesystem.

The temp archive is deleted automatically once the backup finishes. The same applies to restores: they unpack into the same temp location, so TMPDIR must point at a disk large enough for them too.

Last updated on

On this page