meyay/overlayfs-mount repository overview

⁠overlayfs-mount

Create a fuse-overlayfs mount, merging the content of a read only source, and a read/write source folder.

It is based on alpine linux with fuse3, is compiled from fuse-overlayfs sources and leverages s6-overlay's SIGTERM handling to achive clean fuse-overlayfs unmounts when the container is stopped.

See for further details on fuse-overlaysfs: https://github.com/containers/fuse-overlayfs⁠

⁠Docker CLI Usage

docker run -d \
 --name=overlayfs-mount \
 --network none \
 --privileged \
 --env TZ=Europe/Berlin \
 --env PUID=1026 \
 --env PGID=100 \
 --volume $PWD/lower:/lower:ro \
 --volume $PWD/upper:/upper:rw \
 --volume $PWD/work:/work:shared \
 --volume $PWD/merged:/merged:shared \
  meyay/overlayfs-mount:0.5.0

⁠Docker Compose Usage

version: '2.2'
services:
  overlayfs:
    image: meyay/overlayfs-mount:0.5.0
    container_name: overlayfs-mount
    network_mode: 'none'
    privileged: true
    environment:
      TZ: 'Europe/Berlin'
      PUID: '1026'
      PGID: '100'
    volumes:
    - $PWD/lower:/lower:ro
    - $PWD/upper:/upper:rw
    - $PWD/work:/work:shared
    - $PWD/merged:/merged:shared

⁠Parameters

The environment parameters are split into two halves, separated by an equal, the left hand side representing the variable name and the right the value of it.

The volume parameters are split into two halves, separated by a colon, the left hand side representing the host and the right the container side.

The examples form above assume that /lower and /upper exist localy in your filesystem.

If the host path for the /lower bind is a mounted remote share, you might want to switch the propagation from ro to shared.

If the host path for the /upper bind is a mounted remote share, you might want to switch the propagation from rw to shared.

See for further details on docker bind propagation: https://docs.docker.com/storage/bind-mounts/#configure-bind-propagation⁠

⁠Shell access

For shell access while the container is running, docker exec -it overlayfs-mount /bin/sh

⁠Troubleshooting

The filesystem where the host path is located needs to be marked as shared. Otherwise the volume bindings for /work and /merged will result in an error and the container will not start. To mark a filesystem as shared, adopt following line to your needs:

mount --make-shared /

Please use the mount point of your volume, as the mount point "/" is just an example.

If you expose your unionfs folder as a remote share:

• nfs: overlayfs folder is empty
• cifs: overlayfs folder can see and access the content

⁠Docker Swarm

Since the container needs to be run in privliged mode, this image can not be used on Docker Swarm. Sadly, Docker Swarm lacks support for priviliged containers.