Skip to content

Support remote DOCKER_HOST by copying configs and secrets files instead of bind mounting them #11867

Open

Description

@andoks

Description

Per title, currently docker compose uses bind mounts to put configs and secrets in containers, but this does not work when using either docker context or DOCKER_HOST variable to remotely deploy to a different system.

This would help some of the use cases described in these issues:

It builds upon the config content and environment support added in compose-spec/compose-spec#346

Activity

  1. andoks commented on May 30, 2024

    @andoks
    Author

    A suggestion for how to fix this, see the following attached patch that should apply to main branch
    0001-Enable-config.file-s-on-remote-docker-hosts.patch.gz (had to gzip the file, as it would not upload as a plain .patch file)

    I can provide the change as a pull-request if necessary.

  2. andoks commented on May 30, 2024

    @andoks
    Author

    Two alternatives if this change in existing behaviour is undesireable, could be to make the config.driver = "copy" change to this new behaviour, or support a new config.copy property for copying the file into the container/service.

    @ndeloof hope it is ok I am tagging you here, as I saw you were involved in the compose-spec/compose-spec#346 issue

  3. ndeloof commented on May 31, 2024

    @ndeloof
    Contributor

    I fully agree with this direction.
    Regarding change in behavior, I don't feel like this is an issue as long as this is documented in release note.
    A trivial workaround for those who require dynamic sync with container would be to declare an additional bind mount or to rely on a dedicated watch trigger to sync changes

  4. ndeloof commented on May 31, 2024

    @ndeloof
    Contributor

    see the following attached patch

    Please open a pull-request

  5. ndeloof commented on May 31, 2024

    @ndeloof
    Contributor
  6. andoks commented on May 31, 2024

    @andoks
    Author

    see the following attached patch

    Please open a pull-request

    @ndeloof: done -> #11871

  7. LawrenceWarren commented on Jun 4, 2024

    @LawrenceWarren

    This is a good feature that lends itself to a GitOps approach to remote Docker Compose deployments. However I think this should be a toggle, especially with secrets.

    For example, in my workflow I have various docker-compose.ymls each in different directories, with each directory corresponding to a remote server. As a very basic example:

    infrastructure-as-code
    ├── dev
    │   └── instances
    │       ├── dev-server-1
    │       │   └── docker-compose.yml
    │       └── dev-server-2
    │           └── docker-compose.yml
    └── prod
        └── instances
            ├── prod-server-1
            │   └── docker-compose.yml
            └── prod-server-2
                └── docker-compose.yml
    

    This is all Git tracked as a single source of truth to track server state and changes to deployments over time. By being able to use configs from my localhost, we can also track Docker config changes in Git. However, it doesn't make sense to track secrets in the Git repository, as they are meant to be secret - it would be more ideal for my workflow to bind/copy secrets from DOCKER_HOST.

    I think an attribute such as from_docker_host would be useful, so you can explicitly choose where the config/secret files will be found when using Docker contexts, and it is flexible around different workflows people may use:

    configs:
      my_config:
        file: ./service.conf
        from_docker_host: false # Will search my localhost for service.conf
    
    secrets:
      my_secret:
        file: /etc/my-docker-secerts/private.pem
        from_docker_host: true # Will search DOCKER_HOST for /etc/my-docker-secerts/private.pem
  8. andoks commented on Jun 4, 2024

    @andoks
    Author

    @LawrenceWarren: I can see the usecase for that, but IMO that is an entire new feature, with associated tasks. This issue and the connected MR is from my perspective more of a bugfix to make the existing file stanza work at all when interacting with a remote host. However, is the second example of yours (the my_secret one) possible to do with the current bind mount implementation, and this MR would break that use case?

  9. LawrenceWarren commented on Jun 4, 2024

    @LawrenceWarren

    @andoks - You're probably right, my idea/request may be outside the scope of this specific issue. I think in general secrets & configs are not quite perfect when it comes to interactions with Docker contexts. Before creating my own issue to discuss this, I searched GitHub for a similar issue and found this.

    To your question, yes, my example with secrets does work, and I do currently use it to securely write secrets into containers. In my opinion the current behaviour (reading the file path as a path on DOCKER_HOST, and mounting that file) has the correct effect when it comes to secrets, and this merge request would break this workflow.

  10. ndeloof commented on Jun 4, 2024

    @ndeloof
    Contributor

    @LawrenceWarren that's an interesting use-case that demonstrate we can't adopt this feature without considerations for the impacts on existing installations. Bind mounts indeed always target a path on remote Docker Host

  11. LawrenceWarren commented on Jun 4, 2024

    @LawrenceWarren

    @ndeloof Switching to copying does not necessarily break the workflow mentioned above, so long as you're still copying from DOCKER_HOST.

    Of course, the point of this issue is to use copying so that we can source data from localhost, but that is a breaking change if we make it the default behaviour. I am unsure how many people are using my workflow, but we must assume that there are people out there using these features together in their current format, particularly with secrets, since (in my opinion) reading from DOCKER_HOST is probably the desired effect.

    I think having a key to specify where the file is found is a simple solution (and the default should be from_docker_host: true so that existing config does not suddenly have different behaviour), but this expands the scope of the issue and pull request significantly.

  12. ndeloof commented on Jun 4, 2024

    @ndeloof
    Contributor

    so long as you're still copying from DOCKER_HOST.

    Which is a blocker here: Compose being a client-side command, it can't access files on DOCKER_HOST, can only ask daemon to set a bind mount.

  13. andoks commented on Jun 4, 2024

    @andoks
    Author

    @ndeloof: what do you think about introducing a new key (e.g "copy_file", "local_file" or something else that makes sense) that can do it the new way? Or perhaps by setting file: <some-path> in combination with driver: "copy_to_remote" maybe? I am mostly open to anything as long as it enables use of local (configuration) files while deploying remotely. I assume this may also affect the compose spec, which may require a somewhat holistic view

  14. 31 remaining items

  15. ndeloof commented on Jun 16, 2025

    @ndeloof
    Contributor

    @mrtrizer copy sensible file to your remote server, then set compose to use an absolute path:

    secrets:
      foo:
        file: /absolute/path/on/remote/server

    You also can just define a bind mount for your service, as this is actually how things eventually take place:

    services:
      foo:
         volumes:
           /absolute/path/on/remote/server:/run/secrets/foo
  16. mrtrizer commented on Jun 16, 2025

    @mrtrizer

    @ndeloof Thank you, this should do as a workaround. But unfortunately, in this case with absolute paths, I can't test it locally. Is there a way to use relative paths and pass some path of the remote machine as an argument in the compose cli?
    So I could scp ./secrets to path/on/remote and then just do something like compose up --root=path/on/remote

  17. ndeloof commented on Jun 16, 2025

    @ndeloof
    Contributor

    @mrtrizer use an override compose file for local development, to switch remote path to a local one

  18. andoks commented on Jun 16, 2025

    @andoks
    Author

    @mrtrizer

    I'm new to docker and everything looked nice and shiny when I was setting everything up according to the docs and everything was working perfectly locally. But then I got a misleading error about absolute path error. While this problem persists, is there any workaround for this? Without baking the secrets into the images, like I did in the past. Maybe there is an option of building containers with volumes locally and uploading them? Or should I copy everything to the server and run compose there?

    If the content of the files are not too large, you can also consider using the content stanza instead of the file stanza, this way you can test it locally without any work-arounds (except for using content instead of file obviously)

  19. mrtrizer commented on Jun 16, 2025

    @mrtrizer

    In the end I came to this solution. I'm not sure it's entirely secure, but good enough for my application. Use environment variable with empty default value and use the same variable to copy the files to the server. Not much overhead and works almost as I expected it to be working by default with docker compose.

    secrets:
      foo:
        file: ${SECRETS_DIR:-}./secrets/foo.json
    $env:SECRETS_DIR = "/etc/docker/"
    
    scp -r "$($env:LOCAL_SECRETS_DIR)/*" "$($env:REMOTE_HOST):$($env:SECRETS_DIR)$($env:LOCAL_SECRETS_DIR)"
    
    docker-compose --context remote -f $composeFile up --build -d $args
  20. scratchmex commented on Jul 5, 2025

    @scratchmex

    I think reading the localhost file if the source path is relative and the docker host is remote (not unix or win socket). Would that work for backwards compatibility? I think that behavior is broken today so it would be a feature that does not affect current working behavior

  21. scratchmex commented on Jul 31, 2025

    @scratchmex

    this has been asked ten years ago here

  22. scratchmex commented on Jul 31, 2025

    @scratchmex

    gentle ping enumerating all the PRs that were created to fix this and to discuss why they have not progressed, and sadly closed by inactivity

    I volunteer to help in the coding necessary as well

    from the maintainers perspective (@ndeloof @glours @docker/compose-maintainers), what's stopping these feature? apart from time, which not a problem because we have a lot of interested persons able to code it, just the review part will be needed

    cc @andoks @schaubl are you still interested in continuing the work?

  23. JojOatXGME commented on Aug 20, 2025

    @JojOatXGME

    I also think the current behavior of {secrets|configs}.*.file should be changed for multiple reasons:

    • It is inconsistent with {secrets|configs}.*.environment
    • It is allegedly incompatible with the reference implementation of Docker Swarm1
    • It doesn't make any sense with relative paths
    • It prevents people from having a reasonable way to reference config files from their docker-compose.yml

    I have several scenarios where this would make sense, [...] 1. Wrapping docker compose usage in another container - which could carry out bootstrapping and then use the host socket for Compose commands.

    This is what Portainer is doing and what brought me here. It makes it impossible to use any relative paths in compose files.

    How to Fix

    I think the following changes would be possible without causing too many issues with backwards compatibility:

    • Use local file when the path is relative.
    • Keep using remote file when the path is absolute, but generate a warning.
    • Generate a warning even when the Docker Engine is running locally. Uses should be informed about the inconsistency as early as possible.
    • Optionally add a command line option to keep using a bind-mount. Maybe this could be helpful for some people during local development.

    Most people who want to upload local files are probably using relative paths anyway. They are probably talking about files inside the same directory/repository. At the same time, people who have used remote files for secrets have probably used absolute paths. After all, trying to access the path of your current working directory on the remote server doesn't make sense.

    While the goal is to also change the behavior for absolute paths eventually, I think we could keep this implementation for decades. I think being able to use absolute paths is not that important in this context. Note that the warning means we are effectively discouraging absolute paths for secrets and configs altogether.

    I would not introduce a new keyword.

    About finding a long-term solution for secrets on the remote host

    since (in my opinion) reading from DOCKER_HOST is probably the desired effect.

    @LawrenceWarren I don't know. I definetly would not have expected that. Also the offical documentation of secrets uses a relative path, which doesn't make sense when we resolve the path on the remote.

    I use the secrets stanza for our secrets because... that's what it is for, I suppose.

    I agree that in some scenarios you might want to reference secrets which are already stored remotely. I also agree that it would be cleaner if you could do it via the secrets section. However, I was wondering how Docker Swarm handles such scenarios. I would expect to have an option external: true, but according to the spec, this option only exists for configs. Unfortunately, I don't have any experience with Docker Swarm, which might be important to come up with a holistic solution. Anyway, here is my intuition:

    • And an option secrets.*.external to the Compose specification.
    • Implement support for external: true in Docker Compose by using volumes.

    I think a straightforward and intuitive solution to implement external: true is to map them to volumes. Just search for a volume with a specific naming pattern. You should also verify the labels on the volume, which should indicate that the volume in indeed holding a secret. You may also add a command to Docker compose to upload secrets. If Docker ever introduces a native solution for secrets, Docker Compose could transparently switch to the new mechanism at any point.

    Also note that even when you are not using external: true, it would probably be more appropriate to upload secrets and configs into a separate volume. After all, these files are supposed to be mounted read-only.

    secrets abstraction should be preferred over bind mount as this clarify role of mounts in container. Also will allow to benefit native support for secrets if/once docker engine introduce support for those (even when not running in swarm mode)

    @ndeloof I agree, but based on the comments in this issue, the current implementation fails to keep compatibility with Docker Swarm, which might be even more problematic than not automatically getting the advanced security if Docker happens to ever implement native support for secrets. Anyway, my proposal above should resolve this concern as well.

    Footnotes

    1. https://github.com/docker/compose/issues/11867#issuecomment-2232745553 ↩

  24. ndeloof commented on Aug 25, 2025

    @ndeloof
    Contributor

    It is allegedly incompatible with the reference implementation of Docker Swarm[1]

    Swarm is not reference implementation for the compose specification, it just adopted the compose file format at some point in time but didn't adopted recent updates.

    I was wondering how Docker Swarm handles such scenarios

    Swarm relies on engine to manage secrets and config as an actual resource. Standalone Docker engine doesn't have such a feature.

    How to Fix

    Your proposal sounds reasonable but devil is in the details. Any attempt we made to change this behavior resulted into many users to report issues with various corner cases. Typically, if we copy secret into container the same way we do for environment, changes to local file won't be reflected in container and we have no (simple) way to detect this. This would trigger some mismatch and confusion for users.

    I can see two options here

    1. Engine introduces support for secrets/configs. This has been discussed many time, as build would also benefits from such a feature
    2. we introduce an explicit copy pre_start hook, so one can explicitly ask compose to inject a config/secret in container.
  25. JojOatXGME commented on Aug 25, 2025

    @JojOatXGME

    Swarm is not reference implementation for the compose specification

    I would agree that “reference implementation” is not the right word. However, based on the discussion above, my understanding was that the secrets and configs were introduced for Swarm, and Docker Compose followed suite for compatibility.

    I would also say that the implementation of Docker Swarm (as described previously) seems quite reasonable, considering that secrets are often injected on the "build agent" during the deployment. This means you would have the secret available where you process the Compose file, but not necessarily on the host running the Docker Engine. The same applies to configs. It wouldn't surprise me if these options were intentionally implemented to read files from the "build agent", and not from DOCKER_HOST. However, I can only guess about intentions. I might be completely wrong.

    Swarm relies on engine to manage secrets and config as an actual resource.

    Which I think could be mimicked very closely by using volumes.

    I was wondering how Docker Swarm handles such scenarios

    However, I actually meant that I don't know how the Compose file for Docker Swarm would look like for such use case. My intuition would have been that this is the purpose of the external flag, but it doesn't seem to exist for secrets?

    changes to local file won't be reflected in container

    That is correct. This is why I suggested adding a flag to keep this behavior. But yes, it would still be a breaking change which needs to be well documented. I just think that it is a reasonable change to make. If we could somehow distinguish production scenarios from development scenarios with a local engine, we could even use different defaults depending on the scenario.

    I can see two options here [...] Engine introduces support for secrets/configs. [...]

    In this case, I would assume switching to native secrets and configs from the Docker Engine would also break existing behavior in the same way. However, if Docker adding native support is on the horizon, then it makes sense to wait for that, of course.

  26. divStar commented on Nov 25, 2025

    @divStar

    I'd also be interested in this feature since I am running a Docker VM (Flatcar) and connecting to it using Docker. I don't want to manually pre-process the configuration files in order to copy them into the "content" property. I'd much rather like to specify the "file" (in the current folder of the docker-compose.yml for example) and e.g. state, that it should be loaded from_local: true or from_host: false or whatever.

    As matters currently are, I am forced to pre-process this using whatever means, which isn't really helpful, because I want to keep my stack / container set up (I am not using Docker Swarm) as simple as possible.

  27. ndeloof commented on Nov 26, 2025

    @ndeloof
    Contributor

    Suggested workaround:

    services:
      test:
        build: 
           dockerfile_inline:
              FROM <service image>
              COPY config /etc/config
  28. Jwrede commented on Oct 31, 2026

    @Jwrede

    Until Compose has an opt-in for this, I wrote a small wrapper that does the "pre-process into content" step automatically: https://github.com/Jwrede/compose-inline

    It runs docker compose config --format json, and for every config or secret whose file exists on the client it rewrites the model so Compose copies it through the API instead of bind mounting it. Configs become content:. Secrets become environment:, with the value passed only in the environment of the docker compose child process, so it is not written to disk. Then it runs the real command with the rewritten model:

    DOCKER_HOST=ssh://me@server compose-inline up -d
    compose-inline --context prod --bind-files up -d --wait

    --bind-files additionally converts single-file bind mounts from inside the project directory (e.g. ./nginx.conf:/etc/nginx/nginx.conf). Because the files are copied, uid, gid and mode are applied (#9648). Compose does not hash config contents into the service, so the wrapper adds a label with a hash of the inlined files; an edited file then recreates the container on the next up.

    Limits: files are copied at container creation, so there is no live update as with a bind mount. Compose refuses to copy into read_only: true services. Directories and paths that do not exist on the client are left as bind mounts, so the "absolute path on the server" workaround keeps working. Secrets are limited to 128 KiB by the environment. Tested in CI against a docker:dind host over TCP with Compose v2.24.7 and v2.38.2, and locally with v5.0.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions