Docker with Privileged Mode

FlexFS can run inside Docker containers, allowing containerized applications to mount flexFS volumes directly. Because mount.flexfs uses FUSE, the container needs access to /dev/fuse and elevated capabilities.

Option 1: Privileged mode

The simplest approach is to run the container in fully privileged mode:

docker run --privileged \
  -v /path/to/creds:/etc/flexfs/creds:ro \
  your-image

This grants the container full access to the host kernel interfaces, including FUSE.

Option 2: Minimal capabilities (recommended)

For tighter security, grant only the required capability and device:

docker run \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  -v /path/to/creds:/etc/flexfs/creds:ro \
  your-image

• --cap-add SYS_ADMIN — required for mounting filesystems
• --device /dev/fuse — grants access to the FUSE device

Tip

The --cap-add SYS_ADMIN --device /dev/fuse approach is preferred over --privileged because it limits the container to only the capabilities it needs.

Credential setup

Before mounting, the container needs a credentials file. You can either:

1. Bind-mount a pre-existing creds file from the host:

   docker run --cap-add SYS_ADMIN --device /dev/fuse \
     -v /path/to/creds:/etc/flexfs/creds:ro \
     your-image

2. Run mount.flexfs init creds inside the container during startup:

   mount.flexfs init creds \
     --adminAddr admin.example.com:443 \
     --token $TOKEN

The credentials file is a TOML file containing the admin server address, volume token, and optionally the end-to-end encryption secret:

adminAddr = "admin.example.com:443"
token = "$TOKEN"
secret = "$SECRET"

Mounting inside the container

Once credentials are configured, mount the volume:

mount.flexfs start my-volume /mnt/data \
  --foreground \
  --credsFile /etc/flexfs/creds

Note

Use --foreground mode when running in a container so that the mount process stays in the foreground and the container does not exit.

Example Dockerfile

FROM ubuntu:24.04

# Install FUSE3
RUN apt-get update && apt-get install -y fuse3 ca-certificates && rm -rf /var/lib/apt/lists/*

# Copy the flexFS mount client
COPY mount.flexfs /sbin/mount.flexfs
RUN chmod +x /sbin/mount.flexfs

# Create mount point
RUN mkdir -p /mnt/data

# Default entrypoint: mount and then exec the provided command
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

Example entrypoint.sh:

#!/bin/bash
set -e

# Mount flexFS in the background
mount.flexfs start "$FLEXFS_VOLUME" /mnt/data \
  --credsFile /etc/flexfs/creds &

# Wait for the mount to become available
for i in $(seq 1 30); do
  if mountpoint -q /mnt/data; then
    break
  fi
  sleep 1
done

if ! mountpoint -q /mnt/data; then
  echo "Error: flexFS mount failed"
  exit 1
fi

# Execute the provided command
exec "$@"

Running the container

docker run \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  -v /path/to/creds:/etc/flexfs/creds:ro \
  -e FLEXFS_VOLUME=my-volume \
  my-flexfs-image \
  your-application-command

Security considerations

• Store credentials securely; never bake them into the container image.
• Use --cap-add SYS_ADMIN --device /dev/fuse instead of --privileged when possible.
• Consider using Docker secrets or an external vault for credential management.

Next steps

• Docker Compose for multi-container setups
• Mount options reference