What you need to know
Inspect the model produced by cross-folder Compose extends. The documented env_file conversion preserves the source file location, while borrowing a service’s properties does not automatically add that source service.
Potentially affected
Docker Compose projects using extends with a service definition in another folder; docker stack deployment and include model ownership are outside this procedure.
DSE recommendation
DSE recommends comparing the resolved env_file path and resulting service list before accepting an extends refactor.
Bottom line: Inspect the model after moving shared service properties into another folder. Review the actual file selected by the resulting environment-file path and the services present in the assembled project before treating the refactor as equivalent.
Source fact: documented behavior
The Extend your Compose file documentation is the primary reference.
When a service extends a definition in another file, Compose reuses the referenced service’s properties without automatically including that referenced service itself in the final project. The cross-folder example converts relative paths from the extended service so they continue pointing to the original file location. Its env_file: ./container.env example is rendered as ../commons/container.env, and the documentation uses docker compose config to inspect that resulting model.
What the source does not establish
Keep this article confined to the documented extends property and path-conversion behavior. It does not restate the separate include project-directory model or the precedence of competing environment values. Do not assume a valid resolved model proves that the intended file exists, contains approved configuration or will be acceptable to the application. Keep secrets out of model dumps and shared examples.
Applicability questions
- Which service borrows properties from which external definition?
- What exact env_file location should remain in use?
- Which services should exist in the resulting project?
- How will the resolved path be inspected without exposing sensitive values?
DSE recommendation: compare the generated model with the refactor plan
DSE recommends comparing the resolved env_file path and resulting service list before accepting an extends refactor.
Write the intended before-and-after file layout with the service owner. Identify the environment file that should retain responsibility for the selected nonsecret setting. Keep that file’s identity separate from the location of the Compose fragment now describing it. Record whether the referenced base service is intended merely as reusable properties or as an additional running service.
Inspect the resulting model through the documented configuration workflow using the exact managed inputs. Compare the resolved environment-file location with the intended source file. Follow the actual conversion rather than mechanically replacing every relative path with a guessed base-directory path. Redact any sensitive material before retaining an excerpt.
Review the resulting service list beside the ownership plan. If an expected service is missing, decide whether it must be explicitly declared through the supported arrangement. Avoid adding a second service merely because a reusable fragment has a familiar name. Keep dependency, port and volume changes visible instead of treating them as incidental effects of a directory move.
Have the application owner accept the nonsecret configuration outcome independently. A correct path is necessary evidence for this refactor, while application startup and the authority of environment values need their own relevant checks. Preserve both the original model and proposed model for a precise reversal.
Verification and evidence
Proposed verification, not performed: prepare a harmless main-project directory and a neighboring common-definition directory. Give the intended environment file a recognizable nonsecret fixture value and place a deliberately different fixture file at a plausible wrong location.
Extend the shared definition, inspect the actual rendered model and identify which environment file it names. Compare the resulting service list with the proposed design before running an approved disposable service. Retain directory layout, exact inputs, redacted model excerpt and observations. Keep value precedence and the separate include mechanism outside the conclusion; no real application refactor is claimed.
Official references
- Extend your Compose file — Docker Docs.
Source review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.
Review the official source
Docker Docs — Extend your Compose file · Verified October 29, 2026
Need help applying this guidance safely?
DSE can help confirm applicability, protect service continuity, and validate the result across physical security and IT systems.
Talk with DSE