Docker Compose Build Caching#

Overview#

Dokploy's application builds have a per-app cleanCache toggle (merged in PR #1508) that injects --no-cache (Docker/Nixpacks/Paketo/Railpack) or --clear-cache (Heroku) into each builder's command. This field is stored as a boolean column on the application table and defaults to false 1.

Docker Compose deployments have no equivalent setting. The compose table schema 2 contains no cleanCache column, and the compose builder never passes --no-cache or --pull to Docker.

How Compose Builds Work Today#

createCommand in packages/server/src/utils/builders/compose.ts generates one of two fixed commands per composeType:

Neither command includes --no-cache or --pull. As a result, Docker reuses its layer cache on every redeploy — source-code changes that don't invalidate a COPY/ADD layer are silently skipped, and base images are never re-fetched unless the cache is manually busted 3.

The custom command override field is sanitized by sanitizeCommand, which blocks shell control characters including ; and |. && chaining is allowed only when every chained sub-command starts with docker compose — so a multi-step pattern like docker compose pull && docker compose down && docker compose up -d --build is expressible in principle but must match this exact structure 4.

The Stale-Build Problem#

Because --remove-orphans is the only cleanup flag on the default docker-compose command, topology changes — renamed services, removed services that owned volumes, changed network names — can leave the stack in an inconsistent state after a redeploy. Old containers or networks that --remove-orphans cannot fully prune remain running alongside the new stack 5.

The reporter in issue #4992 notes that the expected idiomatic fix (docker compose pull && docker compose down && docker compose up -d --build --remove-orphans) introduces a brief downtime window: containers are fully stopped between down and up, unlike Compose's default in-place rolling recreate. This trade-off should be weighed before adding it as the default.

Note: This problem only applies to composeType === "docker-compose". Swarm (stack) deployments use docker stack deploy --prune, which handles image updates via --with-registry-auth and does not need a separate pull/down step 5.

Feature Gap vs. Application Builds#

Key Files#

Workarounds (Current State)#

1. Custom command override — set compose.command to a &&-chained sequence such as:

   ⧉

   compose -p myapp -f docker-compose.yml pull && compose -p myapp -f docker-compose.yml down && compose -p myapp -f docker-compose.yml up -d --build --remove-orphans
   

   The compose.command value is prefixed with docker by the builder, so each chained sub-command must start with docker compose or docker-compose to pass sanitization 4. This introduces a downtime window.

2. SSH / host-level cache prune — run docker builder prune or docker system prune on the host before triggering a redeploy. This is outside Dokploy's control plane.

Implementing a Fix#

To mirror the application cleanCache feature for Compose, the minimum changes are:

1. Add a cleanCache boolean column to the compose table in packages/server/src/db/schema/compose.ts and generate a Drizzle migration.
2. In createCommand, append --no-cache after --build when compose.cleanCache is true (applies to docker-compose type only; Swarm does not use --build).
3. Optionally add a --pull flag to the up command to force base-image refresh.
4. Expose the toggle in the UI, mirroring the application cleanCache switch added in PR #1508.