76

Title says it all. I've got a few volumes set up as readonly (:ro) but want to test :cached and :delegated for helping with file i/o performance, but couldn't figure out how to set this up in a compose file.

Oh, I already tested:

volumes: - external:internal:cached

2

5 Answers 5

114

Explanation: The purpose of using volumes configuration on docker is to share data between the host and the docker container and ensure data consistency between both (What happens in A(host/container) is represented in B(host/container) and vice versa) . The mounted volume is "part" of the container and relevant. The common usage is to store shared data backup both in container and on file system in machine. If the container is removed, volume still exists and is independent of container state it will be reused and loaded from last persisted state.

TLDR:

  • Use cached: when the host performs changes, the container is in read only mode.
  • Use delegated: when docker container performs changes, host is in read only mode.
  • Use default: When both container and host actively and continuously perform changes on data.
  • Ensure you use an updated docker-compose and docker version on your machine

From Documentation:

Mac uses osxfs to propagate directories and files shared from macOS to the Linux VM. This propagation makes these directories and files available to Docker containers running on Docker Desktop for Mac. **By default, these shares are fully-consistent, meaning that every time a write happens on the macOS host or through a mount in a container, the changes are flushed to disk so that all participants in the share have a fully-consistent view.

Full consistency can severely impact performance in some cases.** Docker 17.05 and higher introduce options to tune the consistency setting on a per-mount, per-container basis. The following options are available:

The consistency option, if present, may be one of consistent, delegated, or cached. This setting only applies to Docker Desktop for Mac, and is ignored on all other platforms.

The Docker volumes flags are:

  1. consistent or default: The default setting with full consistency, as described above.
  2. delegated: The container runtime’s view of the mount is authoritative. There may be delays before updates made in a container are visible on the host. When you use it? For example You use it when the container changes the data continuously and you want to backup this data on the host, this is read only operation on host perspective and therefore the right choice would be delegated.
  3. cached: The macOS host’s view of the mount is authoritative. There may be delays before updates made on the host are visible within a container. When you use it? For example when your host continuously changes data that the container service reads and uses it ( like configuration / source code / rendered data from server etc ...)

Usage:

- <my-first-host-volume>:<first-container-volume-path>:delegated
- <my-second-host-volume>:<second-container-volume-path>:cached

Example:

version: '3.4'
services:

  jenkins:
     image: jenkins/jenkins:lts
     environment:
       - JENKINS_HOME=/var/jenkins_home
     container_name: jenkins  
     volumes:
       - '~/jenkins/:/var/jenkins_home:delegated'
       - '~/environment_keys:/var/data:cached'
     ports:
       - 0.0.0.0:8080:8080
     expose:
       - 5000  
     restart: unless-stopped
7
  • 4
    I can't seem to find documentation for this on the docker-compose website. Could you please provide a link
    – goonerify
    Commented Dec 19, 2020 at 23:27
  • @goonerify docker-compose documentation Link : docs.docker.com/compose
    – Aviv
    Commented Dec 21, 2020 at 12:47
  • 7
    Thanks but there are no references to docker volume flags like consistent, default, delegated and cached in that link
    – goonerify
    Commented Dec 21, 2020 at 15:41
  • 3
    @goonerify I think that these directives are no longer applicable. I can find many articles dating 2018/19 that reference these, but no official documentation mentions it anywhere.
    – Pankaj
    Commented Dec 24, 2020 at 18:03
  • 1
    Docker documentation issue about this. Not documented on Docker Compose (but works on Docker Desktop for Mac 4.0.0) github.com/docker/docker.github.io/issues/11884
    – akauppi
    Commented Sep 13, 2021 at 14:27
24

In my case, I wanted a readonly (:ro) volume that’s also :cached or :delegated. To do this, you simply use this syntax:

volumes:
 - /external/folder:/internal/folder:ro,cached
5
  • 1
    Why would you use cached in combination with ro? My understanding from the docker documentation is that delegated is faster if you don't need additional write consistency guarantees from the container to host, and with ro you'd never write out again?
    – Hultner
    Commented Nov 14, 2019 at 14:57
  • @Hultner In my case, it was a hot-reloaded source-code folder that was then picked up by webpack-dev-server. I wanted to use ro because the container should never need to write to this folder, and cached because I don’t mind the occasional save causing a delay. However, I’d mind it if the way more frequent reads are delayed due to syncing taking place. "As such, cached typically improves the performance of read-heavy workloads, at the cost of some temporary inconsistency between the host and the container." is why I believe it’s best, but the docs aren’t exactly clear about it. Commented Nov 15, 2019 at 16:36
  • As I grasp it from the docs delegated provides even better performance if we can live with delays from writes within the container and cached only adds extra benefit if we want writes from the container to propagate to the host. "delegated: The container runtime’s view of the mount is authoritative. There may be delays before updates made in a container are visible on the host." and "…writes by containers may not be immediately reflected on the host… However, by relinquishing consistency, delegated mounts offer significantly better performance than the other configurations."
    – Hultner
    Commented Nov 18, 2019 at 13:34
  • @Hultner have you tried this for live development with setups like webpack, etc? Did you not have any problems with hot reloading / bundling etc?
    – gen
    Commented Apr 6, 2020 at 15:32
  • @gen Yes I have, I used it in production at a previous client and it worked great, both for me and the rest of the team. I'd say much better performance then without using delegated.
    – Hultner
    Commented May 4, 2020 at 12:18
9

I was not running new enough (edge channel) version of Docker so the commands did not work. After upgrading, everything worked as expected.

4
  • In my case, it worked after a restart... So the syntax is OK :-) Commented May 9, 2017 at 13:03
  • 3
    what version was cached added to docker?
    – Tri Nguyen
    Commented Oct 3, 2018 at 17:16
  • @ReinoutvanRees restart of what? Docker or the containers?
    – gen
    Commented Apr 6, 2020 at 14:39
  • Restart of the whole docker engine. Commented Apr 8, 2020 at 8:46
8

I felt that this thread needed to be updated to reflect the current situation better.

Ever since Docker for Mac started including gRPC-FUSE, these flags have been removed from the Docker documentation as they're no longer needed. It's safe to remove them from your docker-compose.yml files.

https://github.com/docker/for-mac/issues/5402

You can see gRPC-FUSE is selected by default within Docker Desktop. Go to Settings > General tab.

5

This answer is not directly related to the question but serves the same purpose.

The docker-sync project aims at solving those problems of slow syncs on macOS and Windows. I have set it up for some Ruby on Rails app and the results were astonishing. The results should be the same for other types of projects.

Here is my template dockerfile-compose

version: '3.4'
volumes:
  app-code:
    external: true
services:
  backend:
    volumes:
      - app-code/:/app:rw

And the docker-sync file

version: 2
syncs:
  app-code:
    src: './'
    sync_strategy: 'native_osx'
    sync_excludes:
      - '.git'
      - 'coverage'
      - '.gitignore'
    watch_excludes:
      - '.*/.git'
      - '.gitignore'
      - 'log'
      - 'docker-*.yml'

Then you can docker-sync start or follow the documentation to use docker-sync instead of docker-compose to automatically start/stop the sync when needed.

One of the main disadvantages is the dependency with the docker-sync gem that you must install on your OS, but once it's set up it works wonderfully.

1
  • 1
    If you're using the docker-sync file above as reference, don't forget to fix the quote typo if .gitignore entry in sync_excludes. Commented Sep 4, 2022 at 15:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.