Feature Request: Pre/Post-Backup Hooks and Ordered Backup Execution

[muebau]

Hello,
first of all, a big thank you to the maintainer for forking the project, keeping it alive, and continuing to drive it forward!

Some applications require specific commands to be run before a backup can safely proceed. For example, Nextcloud requires occ maintenance:mode --on to be called before backing up to ensure data consistency. Similarly, certain setups may require backups to run in a specific order across services or directories.

It would be great to have support for:

• Pre- and post-backup hooks: user-defined commands that run before and after the backup process
• Ordered backup execution: the ability to define the sequence in which components are backed up
• Ordered hook execution: the ability to define the sequence in which hooks run within a stage (e.g. pre, post, container context)

What do you think about a solution like this?

  backup:
    image: ghcr.io/lawndoc/stack-back
    labels:
      stack-back.ordered: true
      stack-back.order.1: "nextcloud-app"
      stack-back.order.2: "nextcloud-database"
      stack-back.hooks.pre.1.cmd: "sudo -E -u www-data php occ maintenance:mode --on"
      stack-back.hooks.pre.1.context: "nextcloud-app"   # (optional) run inside this container
      stack-back.hooks.pre.2.cmd: "some-global-script.sh"
      stack-back.hooks.pre.2.context: "host"            # (optional) run on host / global context
      stack-back.hooks.pre.3.cmd: "this-container-script.sh"  # runs in this (backup) container
      stack-back.hooks.post.1.cmd: "sudo -E -u www-data php occ maintenance:mode --off"
      stack-back.hooks.post.1.context: "nextcloud-app"  # (optional) run inside this container
      stack-back.hooks.error.1.cmd: "notify-admin.sh 'backup failed'"
      stack-back.hooks.error.1.context: "host"
      stack-back.hooks.finally.1.cmd: "sudo -E -u www-data php occ maintenance:mode --off"
      stack-back.hooks.finally.1.context: "nextcloud-app"

  nextcloud-app:
    image: nextcloud:stable
    labels:
      stack-back.volumes: true
      stack-back.volumes.include: "data"
      stack-back.hooks.pre.1.cmd: "sudo -E -u www-data php occ maintenance:mode --on"   # runs in this container
      stack-back.hooks.post.1.cmd: "sudo -E -u www-data php occ maintenance:mode --off"  # runs in this container

  nextcloud-database:
    image: ...
    labels:
      ....
      stack-back.hooks.pre.1.cmd: "prepare-db-for-backup.sh"   # runs in this container
      stack-back.hooks.pre.1.on-error: "abort"                 # abort the backup (default)
      # stack-back.hooks.pre.1.on-error: "continue"            # log and proceed anyway
      stack-back.hooks.post.1.cmd: "resume-db-to-production.sh"  # runs in this container

A few notes on the intended behavior:

• hook execution order: all backup-container-defined hooks run first, target-container-defined hooks run second
• execution abort on error by default; set on-error: continue to log and proceed instead
• context is optional and defaults to the container where the label is defined
• pre hooks run in sequence before the backup
• post hooks run only if all pre hooks and the backup itself succeeded
• error hooks run only if a hook or the backup itself failed
• finally hooks always run, regardless of outcome
  This follows the same logic as a try/catch/finally pattern which hopefully makes it intuitive to reason about

Container backup order: if stack-back.ordered: true is set, containers are backed up in the sequence defined by stack-back.order.1..n

• container missing from the list: backed up after the ordered ones (warning logged)
• gaps in numbering: gap is skipped, next found number is used (warning logged)
• duplicate label keys (e.g. two order.1): Docker/YAML constraint, last value silently wins
• unknown container name: skipped (warning logged)
• duplicate container name in the list: backed up once (warning logged)
• ordered: true set but no order.n labels defined: falls back to unordered execution (warning logged)

The individual additions are relatively small but I think they unlock some powerful and flexible backup workflows.

Would love to hear your thoughts!

[muebau]

A few things I found:

My idea of context: "host" does not work as it not possible to run "outside of the container", I had a bad feeling when I wrote the lines 😂 So no context => in this container, there is not "host" just container names.

I was not aware that the containers are stopped before backup. This changes the idea a bit as everything is prepared (volumes), stopped (except databases), backup and started again.

The "order" of pre/post on the backup container is:

• all pre on backup container (global stack)
• all pre from the individual containers
• stop containers (except databases)
• backup volumes & sql dump
• start containers (databases still running)
• all post from containers
• all post from backup container (global)
• (error in case of failure)
• finally hook

Errors in the pre hooks skip the stop and backup of the containers (error and finally called).

My idea was that there would be a runtime per container but now that I understood the system it is more a nice way to write the commands in stack order or on the container in question. I like both even if everything is run all at once. The stack-back.ordered: true feature is a bit less powerful now. Still it orders the pre/post hooks of the containers.

I think I will try to implement that and create a pull request.