Docker Compose

This guide shows how to use Docker Compose to run a flexFS mount as a sidecar container alongside your application containers. The sidecar pattern keeps the FUSE mount in a dedicated container that shares its filesystem with the application containers via a shared volume.

Architecture

docker-compose.yml

services:
  flexfs-mount:
    image: flexfs-mount:latest
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse
    security_opt:
      - apparmor:unconfined
    volumes:
      - /tmp/flexfs-shared:/mnt/data:rshared
      - ./creds:/etc/flexfs/creds:ro
    command: >
      start <volume-name> /mnt/data
      --foreground
      --credsFile /etc/flexfs/creds
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mountpoint", "-q", "/mnt/data"]
      interval: 10s
      timeout: 5s
      retries: 3

  application:
    image: your-application:latest
    volumes:
      - /tmp/flexfs-shared:/data:rshared
    depends_on:
      flexfs-mount:
        condition: service_healthy

Mount propagation is Linux-host-only, and :rshared is honored on bind mounts — not on named volumes. To make a FUSE mount created inside the sidecar visible to other containers, bind-mount a host directory into both containers with rshared propagation and make it a shared mount point on the host first (mount --bind it onto itself, then mount --make-rshared). Without that, the application container sees an empty directory.

A sidecar running with SYS_ADMIN and /dev/fuse as shown does not need fusermount3; the mount client talks to the kernel directly. Only a sidecar that mounts as an unprivileged user needs the fuse3 package, and without it the mount fails with the platform FUSE helper is not installed. See Using a dedicated flexFS image.

security_opt: [apparmor:unconfined] is required on hosts running AppArmor (Ubuntu, Debian): Docker’s default profile contains deny mount, so FUSE mounts are blocked even with CAP_SYS_ADMIN. Omit it on hosts without AppArmor.

Step-by-step setup

1. Build the mount image

There is no published mount.flexfs container image, so the flexfs-mount:latest image the compose file names is one you build. Create a build directory holding the mount binary and the Dockerfile shown below, then build it:

mkdir -p flexfs-image
cp /sbin/mount.flexfs flexfs-image/
# save the Dockerfile from "Using a dedicated flexFS image" as flexfs-image/Dockerfile
docker build -t flexfs-mount:latest ./flexfs-image

Alternatively, replace the service’s image: with build: ./flexfs-image and let Compose build it — see Using a dedicated flexFS image.

2. Create the credentials file

cat > creds <<EOF
adminAddr = "<admin-addr>"
token = "<volume-token>"
EOF
chmod 600 creds

chmod 600 is required, not advisory: flexFS refuses to read a credentials file that other users can read. Ownership is not checked, so a file created by a non-root user works when bind-mounted into a container that runs as root.

3. Create the shared directory

Create it and mark it shared, so the FUSE mount made inside the sidecar propagates to the application container:

mkdir -p /tmp/flexfs-shared
sudo mount --bind /tmp/flexfs-shared /tmp/flexfs-shared
sudo mount --make-rshared /tmp/flexfs-shared

4. Start the services

docker compose up -d

5. Verify

# Check mount sidecar health
docker compose ps

# Verify mount inside the application container
docker compose exec application ls /data

Using a dedicated flexFS image

The image built in step 1 comes from this Dockerfile:

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y fuse3 ca-certificates && rm -rf /var/lib/apt/lists/*
COPY mount.flexfs /sbin/mount.flexfs
RUN chmod +x /sbin/mount.flexfs
ENTRYPOINT ["/sbin/mount.flexfs"]

Then reference it in docker-compose.yml:

services:
  flexfs-mount:
    build: ./flexfs-image
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse
    security_opt:
      - apparmor:unconfined
    volumes:
      - /tmp/flexfs-shared:/mnt/data:rshared
      - ./creds:/etc/flexfs/creds:ro
    command: >
      start <volume-name> /mnt/data
      --foreground
      --credsFile /etc/flexfs/creds

Multiple volumes

To mount multiple flexFS volumes, add additional sidecar services:

services:
  flexfs-input:
    image: flexfs-mount:latest
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse
    security_opt:
      - apparmor:unconfined
    volumes:
      - /tmp/flexfs-input:/mnt/data:rshared
      - ./creds-input:/etc/flexfs/creds:ro
    command: start input-volume /mnt/data --foreground --credsFile /etc/flexfs/creds
    healthcheck:
      test: ["CMD", "mountpoint", "-q", "/mnt/data"]
      interval: 10s
      timeout: 5s
      retries: 3

  flexfs-output:
    image: flexfs-mount:latest
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse
    security_opt:
      - apparmor:unconfined
    volumes:
      - /tmp/flexfs-output:/mnt/data:rshared
      - ./creds-output:/etc/flexfs/creds:ro
    command: start output-volume /mnt/data --foreground --credsFile /etc/flexfs/creds
    healthcheck:
      test: ["CMD", "mountpoint", "-q", "/mnt/data"]
      interval: 10s
      timeout: 5s
      retries: 3

  application:
    image: your-application:latest
    volumes:
      - /tmp/flexfs-input:/input:rshared
      - /tmp/flexfs-output:/output:rshared
    depends_on:
      flexfs-input:
        condition: service_healthy
      flexfs-output:
        condition: service_healthy

Create each host directory and mark it shared before starting, as in the single-volume setup:

for d in /tmp/flexfs-input /tmp/flexfs-output; do
  mkdir -p "$d"
  sudo mount --bind "$d" "$d"
  sudo mount --make-rshared "$d"
done

Read-only mounts

To mount a volume as read-only, add --ro to the mount command:

command: start <volume-name> /mnt/data --foreground --credsFile /etc/flexfs/creds --ro

Graceful shutdown

When docker compose down is issued, the mount.flexfs process receives SIGTERM and cleanly unmounts the FUSE filesystem before the container exits.