Skip to content

Add support for additional compose files per stack (extra -f flags)#121

Merged
mstrhakr merged 6 commits into
mstrhakr:devfrom
Joly0:feature/additional-compose-files
Jun 14, 2026
Merged

Add support for additional compose files per stack (extra -f flags)#121
mstrhakr merged 6 commits into
mstrhakr:devfrom
Joly0:feature/additional-compose-files

Conversation

@Joly0

@Joly0 Joly0 commented Jun 12, 2026

Copy link
Copy Markdown

A lot of compose projects ship more than one compose file. A common example is a GPU override like docker-compose.gpu.yml that is meant to be started with:
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

Until now the plugin had no way to do this. It builds the compose command itself, and the only files it would ever pass were the main compose file and the plugin's own override file. The only workaround was adding a COMPOSE_FILE= line to a .env file by hand, which is easy to get wrong and not discoverable at all.

What this PR adds
Selecting additional files (stack settings): There is a new "Additional Compose Files" section in the stack settings. It shows the compose files found in the stack's compose folder (files matching compose.yml / compose.yaml, except the main and override files) as simple checkboxes, soo just tick the ones you want. For files that live outside the stack folder there is a collapsed "External files (advanced)" field where absolute paths can be entered, one per line.

How it is applied: The selection is stored in a small extra_compose_files file inside the stack folder (one path per line, relative paths are resolved against the compose folder). The files are appended as extra -f flags after the main compose file and the override file, so they win in case of conflicts, so basically same order as the manual docker compose command above. Since the plugin builds all command arguments in one central place, this automatically works for every action: up, down, update, pull, logs and autostart.

Viewing and editing the files (editor): The Compose tab in the editor got a small file dropdown. It lists every file the stack is actually made of (main compose file, override file and any additional files) and lets you view and edit each of them. The dropdown only appears when a stack has more than one file, so nothing changes for simple stacks. Switching files with unsaved changes asks for confirmation first.

Safety / design notes

  • The editor endpoints only accept files that are part of the stack's own file list, so they can't be used to read or write unrelated files on the server.
  • Saved entries must be .yml/.yaml, and absolute paths must be under /mnt/ or /boot/config/.
  • Entries pointing to files that no longer exist are skipped with a logged warning instead of breaking the stack.
  • Selecting additional files switches the stack to explicit file mode, so the selection can't be silently ignored when "default file discovery" is enabled.
  • A settings save from an outdated cached browser session (which doesn't know the new field yet) leaves the setting untouched instead of clearing it. Side note: the other settings (envPath, externalComposePath, etc.) are still cleared by such stale saves, that's pre-existing behavior and probably worth a separate look.

Testing

  • 570 PHPUnit tests pass (10 new ones covering the file resolution, ordering, deduplication, missing-file handling and the settings endpoint), PHPStan is clean.
  • Tested live on Unraid with real stacks: a GPU stack (Qwen3-TTS-WebUI with docker-compose.gpu.yml, verified the merged config builds with Dockerfile.gpu and gets the nvidia device reservation) and a multi-file project (OpenTranscribe, which ships ~20 optional compose files plus an upstream docker-compose.override.yml that is now also visible in the editor).

Screenshots
grafik
grafik
grafik
grafik
grafik

mstrhakr and others added 4 commits June 6, 2026 05:11
…ata parsing; [Bug]: [error] 12159#12159: *38373 open() "/usr/local/emhttp/plugins/compose.manager/containers.cache.json" failed (2: No such file or directory) while sending to client

Fixes mstrhakr#117
Until now a stack could only use its main compose file plus the
override file the plugin manages. Many projects ship optional
override files (for example docker-compose.gpu.yml for GPU support),
but there was no way to include them, because the plugin builds the
docker compose command itself and there was nowhere to add another
-f file.

What this adds:

- A new "Additional Compose Files" section in the stack settings.
  It lists the compose files found in the stack's compose folder as
  checkboxes, so you can simply tick the ones you want. An advanced
  field is available for files that live somewhere else (absolute
  paths, one per line).
- The selection is stored in a small extra_compose_files file in the
  stack folder (one path per line) and the files are appended as
  extra -f flags after the main compose file and the override file.
  This automatically applies to every action (up, down, update,
  pull, logs, autostart) because the command arguments are built in
  one central place.
- The editor's Compose tab got a file dropdown that lists every file
  the stack is made of (main file, override file, additional files),
  so all of them can be viewed and edited directly.

Safety details:

- The editor can only open files that actually belong to the stack;
  the request is checked against the stack's own file list, so the
  endpoint cannot be used to read or write unrelated files.
- Saved entries must be .yml/.yaml files and absolute paths must be
  under /mnt/ or /boot/config/.
- A settings save coming from an outdated cached browser session
  leaves the new setting untouched instead of silently clearing it.
- Entries pointing to files that no longer exist are skipped with a
  logged warning instead of breaking the stack.
- Selecting additional files switches the stack to explicit file
  mode, so the selection cannot be ignored by Docker Compose default
  file discovery.
@mstrhakr
mstrhakr changed the base branch from main to dev June 14, 2026 15:58
@mstrhakr mstrhakr self-assigned this Jun 14, 2026
@mstrhakr
mstrhakr merged commit 68d10e1 into mstrhakr:dev Jun 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants