---
title: "Backing Up Docker Volumes"
description: "Back up and restore Koios Docker volumes directly from the command line"
source_url: https://ai-ops.com/docs/installation/backup-restore
---

# Backing Up Docker Volumes

> [!TIP] Use the In-App Backup First
> For nearly all cases, use the in-app backup at **System > Backup** — see [Backup & Restore](https://ai-ops.com/docs/system/backup.md). 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, Django secret key, time-series database token) | Critical |
| `koios_media` | Uploaded files (ML models, component packages) | High |
| `koios_license` | License activation file | High |
| `koios_certs` | SSL certificates | Medium |
| `koios_logs` | Application log files | Low |

The three **Critical** volumes are enough to rebuild a working install. The others carry uploads and configuration that are convenient to keep but recoverable from elsewhere.

## Backup

> [!WARNING] Stop Koios First
> Stop the container before backing up the database volumes. Backing up a live database can produce a corrupt archive.
>
> ```bash
> sudo systemctl stop docker.koios.service   # if running as a service
> docker stop koios                           # if running manually
> ```

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

**Linux / macOS**

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

**Windows**

```powershell
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 three **Critical** volumes (`koios_data_postgres`, `koios_data_influxdb`, `koios_secrets`). Add `koios_media` and `koios_license` if you have uploaded models or an activated license.

## Restore

> [!WARNING] 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 deletes the volume's contents before extracting, so the restore is a clean replacement:

**Linux / macOS**

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

**Windows**

```powershell
docker run --rm `
  -v koios_data_postgres:/data `
  -v ${PWD}:/backup `
  alpine sh -c "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.