Additional Plugin: REST API consumption

[Nodonn89]

Description

BorgBackupServer does not offer a native way to execute REST API requests prior to or following a backup job run.

When backing up applications such as Immich, taking a snapshot of live files and the PostgreSQL database during regular operation is insufficient to prevent data inconsistency. Ensuring a consistent state requires setting Immich into Maintenance Mode via the Immich REST API at the start of the backup process and disabling it once the process completes (or fails).

Description of the Immich API:
https://api.immich.app/endpoints/maintenance-(admin)/setMaintenanceMode

Use Case

Execute an automated, consistent backup of an Immich instance (PostgreSQL database and media storage) using the BorgBackupServer agent in a docker container.

Prerequisites:

• The BorgBackup Agent container and the Immich server container share a common Docker network interface. Already used successfully for backup of PostgreSQL of Immich.

Workflow Execution:

• Pre-Backup Hook: Before backup execution, the agent issues an HTTP REST API request to the Immich server to enable Maintenance Mode.
• Backup Phase: The agent performs the backup operation covering both the PostgreSQL database dump/files and media assets on disk.
• Post-Backup Hook: Upon completion (or failure/cancellation), the agent issues a follow-up REST API request to the Immich server to disable Maintenance Mode.

Maintenance Mode enforces a read-only state on Immich during file and database backup process.

Alternatives Considered

Docker Socket Mounting (/var/run/docker.sock):

• Mounting the host Docker daemon socket into the BorgBackup Agent container to run docker exec commands against target containers.
• Drawback: Bypasses container isolation models, creating a container breakout security vector (root access to host), and also requiring container images to include Docker CLI binaries. Requires additional installation of packages inside container and creates a additional maintenance effort on custom image builds of agent container.