lawndoc / lawndoc/stack-back

Feature request: Atomic backup mode for single snapshot for volumes + databases

Open
#110 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
180
Forks
12
PR merge metrics
No merged PRs in 30d

Description

Problem

Currently, volumes and database dumps are backed up as separate restic snapshots. A volume backup produces one snapshot, and each database dump (restic backup --stdin) produces another. This was mentioned also in #106 . This means:

  • A restore requires identifying and matching the correct volume snapshot with the correct database snapshot(s)
  • There is no guarantee they represent the same point in time
  • For applications like Nextcloud — where the data directory and database must be consistent — this creates a real risk of restoring into an inconsistent state

Proposed solution

A new environment variable ATOMIC_BACKUP (true/false, default false).

When enabled, the backup process changes from:

restic backup /volumes              → snapshot 1
restic backup --stdin db1.sql       → snapshot 2
restic backup --stdin db2.sql       → snapshot 3

to:

docker exec db1 dump > /databases/db1/all_databases.sql   (write to disk)
docker exec db2 dump > /databases/db2/mydb.sql            (write to disk)
restic backup /volumes /databases                          → snapshot 1 (everything)
rm -rf /databases                                          (cleanup)

The resulting snapshot contains:

/volumes/{service}/{path}/...            ← volume data
/databases/{service}/all_databases.sql   ← SQL dumps

A single restic restore retrieves everything needed to reconstruct the stack.

Example usage

backup:
  image: ghcr.io/lawndoc/stack-back
  environment:
    ATOMIC_BACKUP: "true"
    # ... other env vars

No changes to container labels needed — the feature is purely opt-in via the backup container's environment.

Behavior details

  • Default off: When ATOMIC_BACKUP is unset or false, existing behavior is fully preserved (separate snapshots, --stdin piping). No breaking changes.
  • Dump to disk: In atomic mode, each database container's dump command is streamed via docker exec to a file on the backup container's filesystem under /databases/.
  • Single restic call: Both /volumes and /databases are passed to one restic backup invocation, producing one snapshot.
  • Cleanup: The /databases/ directory is removed after the backup completes (regardless of success/failure).
  • Error handling: If a database dump fails, the error is logged and tracked, but remaining dumps and the restic backup still run (consistent with current behavior where one DB failure doesn't block others). The process exits with a non-zero code if any step failed.

Why this matters

For any stack where application data and database state must be consistent (Nextcloud, Gitea, WordPress, etc.), atomic snapshots eliminate the gap between volume and database backups and make restores straightforward — one snapshot, one restore, guaranteed consistency.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files or tests are named, so start by locating the backup orchestration and the existing volume and database dump paths. Compare the current separate restic calls with the proposed ATOMIC_BACKUP branch, then verify that atomic mode creates one snapshot, cleans up /databases on success or failure, and preserves the existing default behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, docker-compose, python
Domain
databases, devops, infrastructure
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.