Is it possible to add an option to integrate container related configuration files/folder to appdata-Backup-Job

[jaydee73]

Currently only the appdata-folder itself will be backed up when running an "appdata-Job". Maybe it would be helpful if the tool can automatically add any kind of configurations/templates related to the container, or at least give the option to do so.

See also: https://forums.unraid.net/topic/198728-plugin-borg-backup-ui-web-ui-for-borg-backup-on-unraid/#findComment-1634803

Regards,
JD

[TheTwist76]

I’ve been thinking a bit more about this feature request, and I’m wondering if a separate Docker/Appdata backup job type might actually be the more robust solution.

Instead of letting the user manually combine arbitrary folders with optional Docker configuration files, the workflow could be container-based:

• Select all containers or only specific containers
• Borg Backup UI automatically determines the corresponding Appdata paths
• Borg Backup UI automatically includes the matching DockerMan XML configuration for those containers
• The user can still add additional folders manually if needed

If all containers are selected, the implementation could simply back up the complete Appdata directory together with the complete DockerMan configuration directory.

For selected containers only, the plugin would resolve the required Appdata paths and corresponding XML files automatically.

I think this would be more reliable than trying to match manually selected folders with container configuration afterwards, because it keeps the backup logically consistent: the Appdata and configuration always belong to the same selected containers.

Would this be roughly what you had in mind for this feature?

[jaydee73]

Sounds good to me!

[borg-codex-bot]

Proposed implementation concept

After reviewing the current wizard, job metadata, Docker runtime control, and Borg runner, the preferred solution is a dedicated Docker/Appdata source mode inside the existing job architecture.

This remains a Borg Backup UI job. It does not introduce a new repository type, a second runner, or a general Docker backup subsystem.

Job model and compatibility

Add an optional source mode:

"source_mode": "manual"

or:

"source_mode": "docker_appdata"

If source_mode is missing, the job is treated as manual. Existing jobs therefore keep their current behavior and no migration is required.

Docker/Appdata-specific settings can be stored as optional job metadata:

{
  "source_mode": "docker_appdata",
  "docker_appdata": {
    "containers": [
      {"name": "Paperless", "stop": true},
      {"name": "AdGuard", "stop": false}
    ],
    "include_dockerman_templates": true,
    "resolved_snapshot": {
      "Paperless": {
        "appdata_paths": ["/mnt/user/appdata/paperless"],
        "template": "/boot/config/plugins/dockerMan/templates-user/my-Paperless.xml"
      }
    }
  },
  "additional_source_paths": [
    "/mnt/user/paperless"
  ]
}

The snapshot records what the wizard detected when the job was saved. It is used for transparency and change detection, not as an unconditionally trusted runtime source list.

Wizard integration

Step 1 receives a source type selection:

• Folders and files
• Docker/Appdata

For a manual job, the wizard remains unchanged.

For a Docker/Appdata job:

1. Step 2 replaces the normal source folder selection with a container selection.
2. Each selected container shows its detected Appdata path or paths and matching DockerMan XML configuration.
3. Automatically detected paths are read-only. The user does not need to enter Appdata paths manually.
4. An optional "Additional folders" section remains available for application data stored outside Appdata, for example /mnt/user/paperless for Paperless documents.
5. The existing backup target and repository selection remains unchanged.
6. The Docker step controls shutdown behavior for the selected containers.

The shutdown behavior should support:

• Stop all selected containers
• Configure shutdown individually
• Do not stop selected containers

When one or more selected and running containers remain active, the existing Appdata risk acknowledgement is required. The warning explains that changing files may cause Borg return code 1 or an inconsistent application backup.

Appdata and Docker configuration discovery

For each selected container, Borg Backup UI should:

1. Read bind mounts using docker inspect.
2. Detect Appdata candidates from host paths containing an appdata path component and common container targets such as /config.
3. Preserve and display multiple matching Appdata mounts when a container uses more than one persistent path.
4. Parse DockerMan XML files below /boot/config/plugins/dockerMan/templates-user/ and match the stored container name instead of relying only on the filename.
5. Include only the matching XML file for a selected container. Selecting all containers must not silently include unrelated DockerMan files.
6. Show a clear warning if no DockerMan XML or no Appdata path can be found.

A missing template should not prevent backing up a valid Appdata path. A missing container or an empty effective source set must fail the precheck with a concrete message.

Runtime behavior

Before borg create, the runner resolves the currently selected containers again and builds the effective source list from:

• detected Appdata paths,
• matching DockerMan XML files,
• manually configured additional folders.

The list is normalized and deduplicated. Sources already covered by a selected parent directory are not added twice.

Current discovery is compared with the saved snapshot:

• unchanged sources continue normally,
• valid changed paths are used but the change is clearly logged,
• missing containers or unusable source paths produce a specific precheck error,
• the job metadata is not silently rewritten during a backup run.

Opening and saving the job again refreshes the stored snapshot after the user has reviewed the current detection result.

The existing Docker runtime logic remains responsible for stopping and restarting containers. For Docker/Appdata jobs, the configured per-container shutdown choices are converted into the existing selected-container stop mode. Existing startup priority and recovery behavior can therefore be reused.

Docker/Appdata jobs should participate in the Docker control resource lock even when no container is stopped, preventing another job from stopping the same containers while this backup is running.

Large source lists

A Docker/Appdata job can produce many source paths. Passing and logging one long joined argument list does not scale well.

The bundled Borg 1.4.5 supports:

• --paths-from-stdin
• --paths-delimiter

The effective source list should therefore be sent to Borg through stdin using a NUL delimiter instead of expanding every path on the command line.

The normal job log should contain a compact summary:

Docker/Appdata sources resolved:
  Containers: 20
  Appdata paths: 22
  Docker configurations: 20
  Additional folders: 3
  Effective Borg sources: 45
Source manifest: <runtime source manifest path>

Only warnings and detected changes should be logged individually. The complete resolved list should be written as a structured JSON source manifest in the configured runtime/status area and included in the support package. It can be replaced by the next run for the same job.

Security and restore behavior

DockerMan XML files may contain environment values or credentials. The wizard should explain this and recommend an encrypted Borg repository.

The feature must not automatically restore DockerMan XML files to /boot or recreate containers. Configuration files remain available through Browse and Restore, download, or extraction to an approved restore target. Applying a restored Docker configuration remains an explicit administrator action.

Initial scope

Included:

• container-based Appdata selection,
• matching DockerMan XML configuration,
• optional additional folders,
• global or per-container shutdown behavior,
• source change detection and transparent logging.

Not included in the initial implementation:

• database dumps,
• Docker images or docker.img,
• Docker Compose stack management,
• automatic container recreation,
• automatic write-back to the Unraid flash drive,
• arbitrary volume or secret management outside the detected paths and explicitly added folders.

Required tests

• Existing manual jobs load and run unchanged without source_mode.
• Container inventory and Appdata mount detection.
• DockerMan XML matching by container name.
• Multiple Appdata paths for one container.
• Additional manual folders.
• Source deduplication and parent-child overlap.
• Global, individual, and no-stop behavior.
• Runtime path changes compared with the saved snapshot.
• Missing container, missing Appdata path, and missing XML handling.
• Borg source delivery through --paths-from-stdin.
• Compact log output and complete source manifest generation.
• Paths containing spaces and other accepted filename characters.

[borg-codex-bot]

Roadmap dependency: Blocked by #447. This feature should be implemented after immutable job IDs are available so that additional container configuration sources and any source manifests can be associated with a stable job identity without introducing another legacy-key migration.