Docker Compose Aware Update Self-Hosted: The Smart Stashboard v7.8 Guide

The docker compose aware update self-hosted path in Stashboard v7.8 does what a raw recreate never could: your “Update now” click now runs docker compose pull and docker compose up -d against the project’s own working directory, honouring env_file, depends_on ordering, and profiles. The big change versus older releases: the per-connection ComposeProjectPath field was removed back in v7.1 — there is nothing to type in by hand anymore. Now docker compose aware update self-hosted discovers the project straight from the container’s labels. New to the tool? Start with the Stashboard dashboard overview, and the update-detection mechanics are covered in depth in the Docker update monitoring self-hosted guide.

What docker compose aware update self-hosted changes: raw recreate vs Compose

The raw “Update now” path has been in Stashboard for a long time. It calls docker stop, docker rm -f, docker create (copying env, mounts, ports, networks, and labels from the old container’s live inspect snapshot), and docker start. For a single self-contained service it is reliable — close to what the one-click container update does. The limitation shows up in Compose stacks: the recreate reads the container’s live environment, not your docker-compose.yml, so any env_file variable you edited since the last docker compose up is invisible, depends_on is skipped, and profiles are never evaluated.

The docker compose aware update self-hosted path instead shells out to the real CLI: docker compose pull <service>, then docker compose up -d <service> — deliberately without --no-deps, so Compose brings dependencies up in the correct depends_on order. The CLI reads docker-compose.yml and every env_file directly from disk at run time, re-resolving everything fresh. Post-start health verification and the full update audit history work exactly as on the raw path.

How Stashboard finds the Compose project without a path field

In v7.8, docker compose aware update self-hosted needs nothing typed in by hand. When a container is started with docker compose up, Docker stamps it with labels automatically, and Stashboard reads exactly those:

• com.docker.compose.project — the project (stack) name the container belongs to.
• com.docker.compose.project.working_dir — the absolute path of the project directory on the host where docker compose up was originally run. This path becomes the working directory for pull + up -d.
• com.docker.compose.service — the service name, passed to the command as the target.

You can confirm the labels are present straight on the Docker host:

docker inspect <container-name> 
  --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}'

If the command prints a path (for example /srv/stacks/home-server), the container is Compose-managed and eligible. If it prints nothing, it was started with docker run or an orchestrator that does not set Compose labels, and Stashboard quietly uses the raw recreate. How docker compose aware update self-hosted then uses that path depends on the connection type.

SSH connections: zero configuration

For SSH connections there is nothing to configure at all. The CLI runs on the remote host over SSH, so the working_dir path from the label exists there natively — right where your Compose files live. Stashboard takes that path as-is, runs docker compose pull + up -d in it, and everything works with no extra fields. This is the simplest case for docker compose aware update self-hosted.

LocalSocket: an optional Compose path mapping

For a local-socket connection the CLI runs inside the Stashboard container. So the stacks directory has to be reachable inside that container at the same path recorded in the working_dir label. The simplest option is to bind-mount your stacks root at the same path on both sides — then no mapping is needed:

services:
  app:
    image: vahac/stashboard:${STASHBOARD_TAG:-latest}
    volumes:
      - stashboard-data:/app/Data
      - /var/run/docker.sock:/var/run/docker.sock   # writable — required for Update now
      - /srv/stacks:/srv/stacks:ro                  # same path → no mapping needed

If you mounted the stacks root inside Stashboard at a different path (say, /srv/stacks on the host → /compose-projects in the container), use the optional Compose path mapping field on the connection form: set a host prefix (/srv/stacks) and a container prefix (/compose-projects). Stashboard rewrites the label’s working_dir to the in-container path, so /srv/stacks/home-server becomes /compose-projects/home-server. The field is optional precisely because an identical mount makes it unnecessary.

What “Update now” actually runs in docker compose aware update self-hosted mode

When docker compose aware update self-hosted is active, the “Update now” click runs two steps in the project’s working directory instead of a raw recreate over the Docker API. Here is the difference between the two paths:

• env_file: on raw, values are frozen from the old container snapshot → under docker compose aware update self-hosted they are re-resolved from disk.
• depends_on ordering: ignored on raw → honoured (dependencies start in declared order).
• Profiles: ignored on raw → evaluated by Compose.
• Pull authentication: raw uses the registry credentials stored on the watch → the Compose path uses the host’s docker login state.

How to confirm docker compose aware update self-hosted activated

Docker compose aware update self-hosted triggers only when every condition is simultaneously true: the container carries the com.docker.compose.project and working_dir labels; the project path is reachable on whichever host runs the CLI (natively for SSH, or via the mount/mapping for LocalSocket); and the docker compose binary is present (it is bundled in the official vahac/stashboard image). If even one condition fails, Stashboard quietly falls back to the raw recreate.

After a successful update, open the Update history accordion in the Docker tab. The audit row for the compose path records the captured docker compose pull + up -d stdout alongside the standard digest transition and a Success badge — unlike the raw recreate, which has no CLI output. That captured output is the most reliable way to confirm docker compose aware update self-hosted actually ran, rather than the fallback path.

⚠️ Risks of docker compose aware update self-hosted you should know

Not every remote connection gets the compose mode. SSH works with zero configuration because the CLI runs on the remote host. But if a remote connection cannot execute docker compose on the target host (for example, TCP+TLS with no shell access), the update stays on the raw recreate. There is no UI badge separating a fallback raw from a deliberate one — when in doubt, check the connection type.

A wrong mapping → the project is not found. For LocalSocket, if the stacks root is not mounted inside the container, or the prefixes in Compose path mapping are wrong, Stashboard cannot find docker-compose.yml at the working_dir path inside its own container. Here docker compose aware update self-hosted fails the attempt with an explicit error rather than silently dropping to a destructive raw recreate. Fix the mount or mapping and retry.

depends_on with condition: service_healthy can block for a long time. When a service declares depends_on with a service_healthy condition, docker compose up -d waits for that dependency to report healthy before starting the dependent container. On a slow host or a database with a long startup, this can push past the command timeout and be recorded as a failed attempt. If that happens, increase start_period in the healthcheck definition.

Private images need host-level docker login. The Compose path uses docker compose pull, which reads from the host’s credential store — not the registry credentials stored on the watch. If the host is not authenticated to the private registry, the pull fails and the old container is left untouched. For private images where only Stashboard holds the credentials, the raw recreate is the safer choice. General image-security practices are in the Docker hardened images guide.

Ready to enable it?

In v7.8, docker compose aware update self-hosted is a clean opt-in by convention: for Compose-managed containers the mode turns on automatically from the labels, and for everything else nothing changes from before. There is nothing to type in by hand — at most you mount the stacks directory (LocalSocket) or do nothing at all (SSH). Your next update picks up the latest env_file values, starts dependencies in the right order, and leaves no recreate drift for a later docker compose up -d to clean up. For the full Stashboard setup from scratch, see the dashboard overview, and for Docker fundamentals the Docker for beginners post.

Stashboard is open source — you can find the full source code on GitHub and pull the ready-to-run image directly from Docker Hub. Issues, PRs, and stars are always welcome. 🙌