Skip to main content

Docker Backup

This guide explains how to safely back up containers, volumes, and configuration in Docker or Podman environments. Creating a backup opens the backup wizard, whose final options screen is titled "Backup Settings". The wizard auto-detects the runtime type (kubernetes/docker/podman, etc.) and handles Docker/Podman backups through the same flow.

Why do you need Docker backups? Docker/Podman containers are ephemeral by nature. When a container is deleted, its internal data disappears. Volumes holding important data and docker-compose configuration must be backed up to enable quick recovery in case of failure.

Prerequisites​

To create a Docker/Podman backup, an external storage must already be registered.

  1. Register an external storage on [Backup Management] > Storage Management.
  2. Use the storage row's Manage Links icon to link the target Docker/Podman host with that storage.
  3. Once linked, the storage appears as a selectable option in the backup creation wizard.

See the Velero/Object Storage Setup guide for full instructions.

Backup Type and Backup Scope (Two-Axis Model)​

KIOPS's Docker/Podman backups separate what to back up (type) from where to take it from (scope).

Excluded on on-prem BasicBackup type → Volumes only Excluded on on-prem BasicContainer backup scope → Compose project

Backup Type​

The internal values are full / volume / config / compose. The modal surfaces them with human-readable labels.

  • Full backup (full): Volumes + container configuration + Compose file
  • Volumes only (volume): Volume data only
  • Configuration only (config): Container configuration only
  • Compose file only (compose): docker-compose.yml file only

Service backups (the service backup creation dialog) additionally retain the docker-compose definition.

Backup Scope​

The backup scope is chosen from one of three radio options on the Backup Settings screen.

  • All containers: Targets all containers/volumes on the infrastructure.
  • Compose project: Backs up per Docker Compose project running on the target host. The project list is derived from the com.docker.compose.project container label.
  • Select containers: Manually multi-selects the containers to back up.

What about image backups? The backend model does not have a standalone "image backup" type. Images are expected to be re-pulled from a container registry.

Backup Procedure​

Create Docker/Podman backups from the [Backup Management] page in KIOPS.

Step 1: Navigate to Backup Management​

  1. Click [Backup Management] in the left menu.
  2. Click Create Backup at the top.

Step 2: Select Runtime and Storage​

  1. Runtime: Pick the target Docker or Podman host.
  2. External storage: Pick one of the storages already linked through Manage Links.

What is a runtime? A runtime refers to a Docker/Podman host registered in KIOPS. Multiple servers may each appear as a different runtime.

Step 3: Choose Backup Type​

Pick one of Full (volumes + container config + Compose file), Volume only, Config only, or Compose file only.

Step 4: Choose Backup Scope​

In the Backup Scope radio group on the Backup Settings screen, choose one of the following three options. SSH credentials were already entered in an earlier wizard step, so switching the scope makes the modal load the relevant list automatically.

  • All containers: Proceeds without additional input.
  • Compose project: Selecting this scope auto-fetches the target host's Compose project list; pick one from the dropdown.
  • Select containers: Selecting this scope auto-fetches the container list; multi-select one or more with checkboxes.

When the list is empty — If no Compose projects or containers are running, the list may be empty. Use the refresh button next to the list to query again.

Step 5: Run the Backup​

  1. Confirm the chosen options.
  2. Click Start Backup.
  3. Progress is displayed on screen.

Cautions during backup — Containers that share a volume being backed up may become temporarily slow. When possible, run backups during low-traffic periods.

Backend Metadata​

Each backup record carries the following metadata.

  • storage_type: The type of external storage used. Because an external storage connection is required, Docker/Podman backup records store the default value minio (valid values: local, minio, nfs). This is separate from the type you pick when registering external storage, such as SeaweedFS. For compatibility, the backup record's storage_type label stays minio.
  • What triggered the backup: One of four values:
    • manual - Triggered manually by the user from the modal
    • pre_deploy - Automatic backup taken just before a deployment
    • post_deploy - Automatic backup taken just after a deployment
    • scheduled - Triggered by a scheduler
  • status: pending, in_progress, completed, failed

These values are surfaced directly in the backup list and recovery history tabs.

Backup List Filters​

The Docker/Podman backup list lets you narrow records with the following filters.

  • Compose Project Filter: Filter the backup history by Docker Compose project name. Useful on Docker hosts that run multiple projects when you want to view only one project's backups.
  • Type Filter: Filter the list by backup type — Full, Volume only, Config only, or Compose file only.

Understanding the Backup Process​

Knowing what KIOPS does internally helps with troubleshooting.

Volume Backup Method​

Volumes are compressed into tar files using a temporary container.

# KIOPS internal operation example
docker run --rm \
  -v volume_name:/data \
  -v /backup:/backup \
  alpine tar cvf /backup/volume_backup.tar /data

Configuration Backup Method​

For service backups, docker-compose.yml and related configuration files are bundled together.

Automatic Backups and trigger_type​

The Docker/Podman backup modal has no Daily/Weekly/Monthly schedule UI. You cannot set a schedule directly from the backup wizard; instead, the backend trigger_type metadata indicates how the backup was launched.

  • manual - The user clicked Start Backup in the modal
  • pre_deploy / post_deploy - Triggered automatically by the deployment pipeline
  • scheduled - Triggered by a separate scheduler

Recommended operational pattern — Use the deploy-time auto backups (pre_deploy / post_deploy) to preserve state immediately before and after changes - no schedule needs to be configured in the modal.

Troubleshooting​

Volume Backup Failure: "volume is in use"​

Error: volume is in use

Why does this happen? Another container is using the volume. Backup of in-use volumes may be restricted to ensure data consistency.

Resolution

  1. Pause the container: Pause containers using the volume and retry the backup.
  2. Run during off-hours: Schedule the backup during low-traffic periods.

Insufficient Disk Space: "No space left on device"​

No space left on device

Why does this happen? Not enough disk space to store the backup file. Common when backing up large volumes.

Resolution

  1. Clean up old backups: Remove unnecessary backups from [Backup Management]. Deleting removes both the backup record and the backup file in storage. The confirmation message lists what was removed, and states explicitly when the storage file could not be deleted.
  2. Expand external storage capacity: Grow the registered external storage or switch to a different one.
  3. Remove the temporary working directory on the runtime server: Once the backup file is uploaded to storage, the temporary directory is cleaned up automatically. A backup that fails midway leaves it behind. Enter the SSH details in the delete dialog to remove it as well.

There is no retention setting that deletes old backups automatically. Delete old backups yourself.

Monitor disk space — To prevent backup failures, monitor disk usage regularly. Keep at least twice the total backup size as free space.