Skip to main content

Docker Backup

This guide explains how to safely back up containers, volumes, and configuration in Docker or Podman environments. The backup creation modal is titled "Create Docker/Podman Backup" and auto-detects the runtime type (including runtimeType === 'podman').

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

Backup Type (BackupOptionsModal)​

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 (ServiceBackupFormModal) additionally retain the docker-compose definition.

Backup Scope​

The backup scope is chosen from one of three radio options (the backupScope field in BackupOptionsModal).

  • 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 via InfraLinkModal.
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 / volume / config / compose as described above.

Step 4: Choose Backup Scope​

In the Backup Scope radio group on the Backup Settings (BackupOptionsModal) 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: Type of external storage used (e.g. seaweedfs)
  • trigger_type: One of four values (per docker_backup.go:28):
    • 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 (BackupHierarchyView) 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, such as full / volume / config / compose.

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. The radio-based schedule input exists only in the legacy BackupFormModal used for K8s backups; Docker/Podman backups cannot set a schedule directly from the modal.

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].
  2. Expand external storage capacity: Grow the registered external storage or switch to a different one.
  3. Reduce retention period: Shorten the automatic backup retention so old entries are pruned.
Monitor disk space

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