Backing Up Docker Volumes

Use the In-App Backup First

For nearly all cases, use the in-app backup at System > Backup & Restore. See Backup & Restore. It runs without stopping Koios, supports scheduled retention, and produces a single archive you can download.

This page exists for the cases where the in-app backup isn't an option.

When You'd Use This

Scenario	Why direct volume access
Koios won't start or is otherwise unreachable	The in-app UI is unavailable, so the only way to capture state is directly from the volumes
Migrating to a new host	Lets you move the raw volumes between machines without going through the app
Host-level disaster-recovery scripts	Volumes can be snapshotted from the host on the same schedule as the rest of your infrastructure

If none of these apply, stop here and use the in-app backup instead.

Docker Volumes

All Koios data lives in seven Docker volumes:

Volume	Contents	Priority
`koios_data_postgres`	Configuration database (devices, tags, users, models)	Critical
`koios_data_influxdb`	Time-series database (historical tag values)	Critical
`koios_secrets`	Auto-generated credentials (database passwords, the application secret key, time-series database token)	Critical
`koios_media`	Uploaded files (ML models, component packages, stack wheels) and the built stacks	Critical
`koios_license`	License activation file	High
`koios_certs`	Certificates, including any web-interface certificate you installed and its private key	Medium
`koios_logs`	Application log files	Low

The four Critical volumes are enough to rebuild a working install. The other three carry uploads and configuration that are convenient to keep but recoverable from elsewhere — though losing koios_certs drops the web interface back to its built-in self-signed certificate, so you would need to install your certificate again.

Stacks live on koios_media

The wheels uploaded into a stack are stored only on koios_media, and they are the only source a stack can be rebuilt from. Restore without it and every component environment attached to a stack is left with nothing to run.

That volume also holds the built stacks, which the in-app backup deliberately leaves out — they are large and specific to the machine and CPU architecture that built them, and the in-app restore rebuilds them from the archived wheels. A raw archive of the volume captures them, so expect a much bigger archive, and expect to rebuild the stacks by hand if you restore onto a different machine. Exclude the stacks/ directory when archiving this volume by hand, or use the in-app backup instead.

Backup

Stop Koios First

Stop the container before backing up the database volumes. Backing up a live database can produce a corrupt archive.

If your service file was written before v1.2.5, first update its ExecStart and ExecStop lines and reload systemd as described in Running Koios as a Service, so the database has time to shut down cleanly.

sudo systemctl stop docker.koios.service   # if running as a service
docker stop -t 60 koios                     # if running manually

Linux / macOS

Windows

Back up a volume by running a temporary Alpine container that mounts the volume and creates a tar archive in the current directory:

docker run --rm \
  -v koios_data_postgres:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/koios_data_postgres.tar.gz -C /data .

Run the same command for each volume you want to back up, swapping the volume name and archive filename. At minimum, back up the four Critical volumes (koios_data_postgres, koios_data_influxdb, koios_secrets, koios_media). Add koios_license to keep an activated license, and koios_certs to keep an installed web-interface certificate.

To leave the built stacks out of the koios_media archive, exclude the stacks/ directory:

docker run --rm \
  -v koios_media:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/koios_media.tar.gz --exclude=./stacks -C /data .

The uploaded wheels are still archived, so you can rebuild each stack from Components > Stacks after restoring.

Restore

Stop Koios Before Restoring

Restoring into a running container will corrupt the databases.

Stop Koios, then restore each archive back into its volume. This command reads the whole archive first, then deletes the volume's contents before extracting, so the restore is a clean replacement. A missing or damaged archive leaves the volume as it was:

docker run --rm \
  -v koios_data_postgres:/data \
  -v $(pwd):/backup \
  alpine sh -c "tar tzf /backup/koios_data_postgres.tar.gz > /dev/null && rm -rf /data/* && tar xzf /backup/koios_data_postgres.tar.gz -C /data"

Repeat for every volume you need to restore, then start Koios again.

If only koios_data_postgres was lost, Koios starts with a new, empty configuration database, and the saved copies of the old one are still on koios_media: the copy taken before each upgrade, and any archive from System > Backup & Restore. Stop Koios and restore one with step 3 of Downgrade to a Previous Version, using the image you run now.

What's Next

Backup & Restore: the in-app backup that runs without stopping Koios and supports scheduled retention.

Running Multiple Instances Protocols