Skip to main content

Docker Backup

This guide explains how to safely back up running containers, data volumes, and images in a Docker environment.

Why do you need Docker backups?

Docker containers are ephemeral by nature. When a container is deleted, its internal data is lost as well. You must back up volumes containing important data and custom images to enable quick recovery in case of failures.

Understanding Backup Targets​

Learn about the three elements you can back up in a Docker environment.

  • Volumes (High Priority): Persistent storage containing application data. Should be your top backup priority.
  • Images (Medium Priority): Image files required to run containers. Can be pulled from registries again.
  • Containers (Low Priority): Current state of running containers. Can be recreated from images.
Prioritize volume backups

Images can be pulled from registries again, and containers can be recreated from images. However, user data stored in volumes may be unrecoverable, so they should be your top backup priority.

Backup Procedure​

You can easily create Docker backups from the [Backup Management] page in KIWI.

Step 1: Navigate to the Backup Management Page​

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

Step 2: Select Backup Target​

  1. Runtime: Select the Docker runtime environment to back up
  2. Backup type: Select Docker Backup
What is a runtime?

A runtime refers to a Docker host registered in KIWI. If Docker is installed on multiple servers, each may be registered as a different runtime.

Step 3: Select Backup Items​

Select the items to back up. You can save backup time and storage space by selecting only what you need.

  • Volumes: Select Docker volumes containing data (most important)
  • Images: Select custom or important images .
  • Containers: Select containers whose current state you want to save .

Step 4: Run Backup​

  1. Review the selected items .
  2. Click the Start Backup button .
  3. Backup progress will be displayed on screen
Caution during backup

During volume backup, containers using that volume may temporarily slow down. If possible, run backups during low-traffic hours.

Understanding the Backup Process​

Understanding how KIWI performs backups internally helps with troubleshooting.

Volume Backup Method​

Volumes are compressed into tar files using a temporary container.

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

Image Backup Method​

Images are exported to tar files using the docker save command.

# KIWI internal operation example
docker save -o image_backup.tar image_name:tag

Automatic Backup Setup​

Manually backing up every time is tedious and easy to forget. Set up automatic backup schedules to ensure regular backups.

Schedule Options Explained​

  • Frequency: Set the backup execution time using a Cron expression .

    • Example: 0 3 * * * - Run daily at 3 AM
    • Example: 0 2 * * 0 - Run every Sunday at 2 AM

  • Target: Select items to include in automatic backups .

    • Recommended: Set all volumes as targets .

  • Retention Period: Set the auto-deletion period for old backups .

    • Example: 7 days - Backups older than 7 days are automatically deleted .
Recommended backup schedules
  • Development environment: Daily, 3-day retention .
  • Production environment: Daily + weekly, 7-day/30-day retention respectively .

Troubleshooting​

Volume Backup Failure: "volume is in use"​

Error: volume is in use

Why does this happen?

This occurs when 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. Force backup: Enable the Force backup option in backup settings (use with caution for data consistency)
Caution when using force backup

Force backup may capture data while it's being modified, potentially causing data inconsistencies during restoration. When possible, stop containers before backing up.

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

No space left on device

Why does this happen?

There isn't enough disk space to store the backup file. This often occurs when backing up large volumes or images.

Resolution

  1. Clean up old backups: Delete unnecessary backups from the [Backup Management] page
  2. Change backup storage path: Change the backup path to another disk with available space .
  3. Reduce retention period: Shorten the retention period for automatic backups so old backups are deleted automatically .
Monitor disk space

To prevent backup failures, regularly check disk usage. It's best to maintain at least twice the total backup size in free space.