Docker Volume

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

In your databases.json (or .toml) file, configure the following block.

databases.json

{
  "name": "Test database 14 - Docker Volume",
  "type": "docker-volume",
  "volume_name": "<volume_name>",
  "generated_id": "...",
  "container_name": "<container_name>"
}

Generate UUID for your configuration

Generating...

Specific Parameters:

volume_name: (Required) The name of the Docker volume to back up.
container_name: (Optional, but recommended) The name of the container the volume is attached to. Without it the backup/restore still works, but the agent cannot restart the container automatically 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.

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.

Configuration

Docker Compose Example

Temporary storage and disk space

Redirect the temp directory

On this page