How to back up a InfluxDB Docker container (2026)
The correct way to back up a InfluxDB container is a logical dump, not a file copy. Run `influx backup /backup/influx # (v2; v1 uses influxd backup -portable /backup)` inside the container and back up its output. Copying /var/lib/influxdb2 while influx is writing produces an inconsistent snapshot; the backup command snapshots TSM shards and metadata through the engine, so background compaction never leaves you with a torn on-disk copy.
What Dockstash detects
| Env keys detected | DOCKER_INFLUXDB_INIT_USERNAME, DOCKER_INFLUXDB_INIT_PASSWORD, DOCKER_INFLUXDB_INIT_ORG, INFLUXDB_HTTP_AUTH_ENABLED |
|---|---|
| Default port | 8086 |
| Live data paths (never copied live) | /var/lib/influxdb2, /var/lib/influxdb |
| Example images | influxdb:2.7, influxdb:2, influxdb:1.8, influxdb |
Back up InfluxDB with Dockstash, step by step
Create your Dockstash account and open the dashboard
Sign up free at app.dockstash.com/register. The one-time setup wizard asks for your storage VPS (the machine that will hold the encrypted backups) and generates an encryption password — save that password in a password manager immediately, it is shown exactly once.
Add the Docker project that runs InfluxDB
On the Projects screen Dockstash auto-detects every Compose project folder on the server (by default under /var/www). Pick the project that contains your InfluxDB service. Nothing is backed up yet — you are just telling Dockstash where the project lives.
Check that InfluxDB was detected
Open the project and look at the Plan tab. Dockstash reads docker-compose.yml, recognizes the influxdb image and its major version, and adds a database layer with the right backup command — influx backup for v2, influxd backup -portable for v1 — plus the container name it resolved and the env keys it found (DOCKER_INFLUXDB_INIT_USERNAME, DOCKER_INFLUXDB_INIT_PASSWORD, DOCKER_INFLUXDB_INIT_ORG). You can toggle files, databases, and proxy configs on or off before saving.
Optional: sanity-check the backup command by hand
If you want proof before automating, run influx backup into a temporary path inside the container. You should see it write shard and metadata files as it snapshots each bucket through the HTTP API — that engine-coordinated snapshot is what gets backed up, never the live TSM directory.
docker exec <influxdb-container> influx backup /tmp/influx-testConfirm your storage destination
Backups are stored as encrypted restic snapshots on your own storage VPS over SSH. If you completed the setup wizard this is already configured; you can change host, user, port, or the SSH key any time under Settings → Storage.
Set a backup schedule
On the project’s Schedule tab pick daily, weekly, or a custom cron expression (validated inline). Time-series data accumulates fast, so daily is the right default — hourly if your metrics are business-critical. Add a weekly prune schedule with your retention policy so old snapshots are trimmed automatically.
Run the first backup now
Click Backup Now on the project card. Dockstash runs the version-correct backup command inside the running container — influx backup through the HTTP API on v2, influxd backup -portable on v1 — and streams the snapshot straight into restic. You can watch the live restic output line by line in the log panel while it runs.
Confirm the snapshot exists
When the run finishes, the project card shows the new last-backup time, snapshot count, and repository size. Open the Snapshots screen and you will see the restore point in the timeline — that is your proof the backup landed off-site.
The dump command
influx backup /backup/influx # (v2; v1 uses influxd backup -portable /backup)The restore command
influx restore /backup/influx # (v1 uses influxd restore -portable /backup)the backup command snapshots TSM shards and metadata through the engine, so background compaction never leaves you with a torn on-disk copy.
Restore a InfluxDB backup and prove it works
An InfluxDB backup is only real once it has restored. Dockstash restores never overwrite your live time-series data by default — you restore to a fresh location first, check the buckets, and promote them deliberately.
Pick a restore point
Open Snapshots, select the project, and browse the timeline of restore points. Each row is a consistent engine-level snapshot of your TSM shards and metadata — buckets, retention policies, and users — plus the project files captured in the same run.
Restore to a new location
Click Restore and keep the default "Restore to new location" mode. Type the project name to confirm — this is a deliberate, typed-confirm action. The backup files land in the target path you choose, leaving the live project untouched.
Verify the restored data
Load the restored backup into a scratch InfluxDB container with influx restore (or influxd restore -portable on v1), then list the buckets. Every bucket you expect should appear with its retention policy; run a quick query against a recent time range to confirm the newest points made it in.
docker exec <influxdb-container> influx bucket listPromote when satisfied
Once the restored data checks out, point your app at it (or repeat the restore with "Overwrite existing" — an explicit opt-in). Better: let the weekly restore drill do this proof automatically so a restore is never your first rehearsal.
Gotchas to avoid
- Never restic the live TSM/WAL directory — shards are compacted in the background so a raw copy is inconsistent.
- InfluxDB v2 uses `influx backup` (HTTP API + token); v1 uses `influxd backup -portable`. Dockstash detects the major version.
- v2 backups need an operator token with read access; without it the backup call is unauthorized.
Common InfluxDB backup problems
- Symptom
- The backup command errors with "unknown command" or unrecognized flags.
- Cause
- The v1 and v2 command lines are completely different: v2 uses influx backup against the HTTP API, v1 uses influxd backup -portable. Running one generation’s command against the other fails immediately — common after upgrading the image tag.
- Fix
- Check which major version the container runs (influxd version), then use the matching command. Dockstash detects the major version from the image and picks the right one automatically; re-run detection on the Plan tab after an upgrade.
- Symptom
- influx backup fails with "unauthorized" or a 401 from the API.
- Cause
- v2 backups go through the HTTP API and require an operator (all-access) token. A regular read token — or no token at all when auth is enabled — is not enough.
- Fix
- Supply an operator token with read access to the buckets. If you used the DOCKER_INFLUXDB_INIT_* env keys, the init admin token works; otherwise create one with influx auth create --all-access and add it to the plan’s credentials.
- Symptom
- A backup made by copying /var/lib/influxdb2 will not start, or queries return partial data.
- Cause
- InfluxDB compacts TSM shards in the background. A raw copy of the live directory catches shards mid-compaction — some files from before, some from after — producing a torn, inconsistent store.
- Fix
- Never copy the live data directory. Use the engine’s backup command, which snapshots shards and metadata consistently — this is what Dockstash runs. A torn raw copy is generally unrecoverable; restore from a proper backup instead.
Do it in one click with Dockstash
Dockstash runs the exact dump above, restics it off-site, and drill-tests the restore automatically — no script to maintain.
Last updated: July 2026
Frequently asked questions
What command backs up InfluxDB correctly?
For v2, `influx backup` against the HTTP API with an operator token. For v1, `influxd backup -portable`. Both snapshot TSM shards and metadata consistently. Dockstash detects the version and runs the right one.
Can I copy the shard files directly?
No. InfluxDB compacts TSM shards in the background, so a live directory copy is inconsistent. Use the backup command, which coordinates a consistent snapshot through the engine.
What token does the v2 backup need?
An operator (all-access) token with read permission on the buckets. Dockstash detects the init token env keys; supply a token if auth is enabled.
How do I restore a time series backup?
Use `influx restore` (v2) or `influxd restore -portable` (v1) against a fresh instance. Dockstash restores to a staging instance first before any overwrite.
How often should I back up InfluxDB?
Daily works for most metrics workloads; go hourly if losing an hour of points would hurt. On the Free tier backups are manual Backup Now runs; Pro adds scheduled backups up to hourly, and Business allows any cron expression. Pair the schedule with a weekly restore drill for standing proof.
Does backing up block writes to InfluxDB?
No. The backup command snapshots shards through the engine while the server keeps accepting writes — your collectors and dashboards keep running during the backup.
Where do the backups actually live?
On your own storage VPS, as encrypted restic snapshots pushed over SSH. Dockstash never holds your data on a third-party cloud — you point it at a box you control, and the repository is encrypted with a password only you have.
How do I know the backup is restorable without doing a manual restore?
Schedule a restore drill. Dockstash restores the latest snapshot into an isolated scratch workspace, byte-hashes every file against the source, and checks the restored dump — then stamps a pass/fail badge on the project. A weekly drill means you always have fresh proof.