studioetrange/bindfs repository overview

⁠Docker volume plugin for bindfs

With this plugin you're able to mount a given path and remap its owner and group.

This plugin use bindfs tool to managed mounted folders. https://bindfs.org/⁠

⁠Plugin features

• support multiple volume with same mount points
• add more info and clean build process
• resolve bindfs defunct process each time a volume is destroyed
• isolate bindfs-state.json state file for each plugin version
• make concurrent usage of the plugin more robust to be used in a context with a lot operation of volume
• when building plugin you can choose a bindfs to build (consult available versions from here⁠)
• support multi platform for linux/amd64 and linux/arm64

⁠Project History

The original project was maintained here https://github.com/clecherbauer/docker-volume-bindfs⁠, closed on may 2024 and was inspired on https://github.com/vieux/docker-volume-sshfs⁠, closed on oct 2022.

⁠Usage

⁠Install the plugin

• This will install the pre-built versions of the plugin.

  docker plugin install ghcr.io/studioetrange/bindfs:latest
  

  Copy

• To choose an arch :

  docker plugin install ghcr.io/studioetrange/bindfs:latest-arm64
  docker plugin install ghcr.io/studioetrange/bindfs:2.4-arm64
  docker plugin install ghcr.io/studioetrange/bindfs:latest-amd64
  

  Copy

  NOTE : By default this is an amd64 image, when no arch is specified the tag name. (i.e : ghcr.io/studioetrange/bindfs:latest is an amd64 image)

⁠Official repository and available built versions

The main repository for this plugin is Github Container Registry. DockerHub may contains some other test versions and may have a restricted acces.

In Github Container Registry ghcr.io/studioetrange/bindfs⁠ and in docker hub studioetrange/bindfs⁠ available versions are

• Github worflow will built and publish versions for Github Container Registry and docker hub when a git tag is created

• ARM64/AMD64 versions are identified with "-arm64" and "-amd64" in tag name. When there is no arch in tag name, this is an amd64 version

• Versions ending with a letter (i.e : a) or rc are test and prerelease versions. Do not use them in production.

⁠Create a volume

Create a volume which have the current user id and group id mapped to root user (uid/gid 0)

```
docker volume create -d ghcr.io/studioetrange/bindfs:latest -o sourcePath=$(pwd) -o map=$(id -u)/0:@$(id -g)/@0 myvolume

docker volume ls

DRIVER                          VOLUME NAME
studioetrange/bindfs:latest      myvolume
```

Use bindfs options : bindfs options⁠

```
docker volume create -d ghcr.io/studioetrange/bindfs:latest -o sourcePath=$(pwd) -o map=$(id -u)/0:@$(id -g)/@0 [-o <bindfs -o options>] myvolume
```

⁠Use the volume

docker run -it -v myvolume:<path> busybox ls -la <path>

⁠Example for docker-compose file

export EUID=$(id -u)
export EGID=$(id -g)

version: '2'
services:
    app:
        image: busybox
        command: "ls -la /mnt/test"
        volumes:
          - data:/mnt/test

volumes:
    data:
        driver: ghcr.io/studioetrange/bindfs:latest
        driver_opts:
            sourcePath: "${PWD}"
            map: "${EUID}/0:@${EGID}/@0"

⁠Plugin development

⁠Build plugin

• Quick build commands:

  git clone https://github.com/StudioEtrange/docker-volume-bindfs
  cd docker-volume-bindfs
  make all
  

  Copy

  This will build plugin, tagged as latest, delete plugin if he already exists and install it

• Options : you can choose the tag name for the plugin version with PLUGIN_TAG and select a bindfs version with BINDFS_VERSION (default is 1_18_4)

  make PLUGIN_TAG=2.4 BINDFS_VERSION=1_18_4 all
  
  # without using docker cache :
  make PLUGIN_TAG=2.4 BINDFS_VERSION=1_18_4 all-nocache 
  

  Copy

⁠Select a target platform

• Available supported platforms : linux/amd64 and linux/arm64. By default, the current host platform is used.
• You can force to select a supported platforms using any make target by setting PLATFORM variable with amd64 or arm64

  make PLATFORM=amd64 PLUGIN_TAG=2.4 BINDFS_VERSION=1_18_4 all
  make PLATFORM=arm64 PLUGIN_TAG=2.4 BINDFS_VERSION=1_18_4 all
  

  Copy
• The build target will generate an image tag joining PLUGIN_TAG and PLATFORM : 2.4-amd64. If no PLATFORM is setted, then the image tag will be : 2.4
• If you select a platform different from the host, you have to use qemu emulators (see https://gist.github.com/StudioEtrange/ab9b118b778fac8e815c872826ed2cd8#run-multiplatorm-images⁠)

  docker run --privileged --rm tonistiigi/binfmt -install linux/arm64
  docker run --privileged --rm tonistiigi/binfmt -install linux/amd64
  

  Copy

⁠Enable built plugin

• This will enable the plugin, you need this before using it

  make enable
  

  Copy

• Choose the version to enable

  make enable PLUGIN_TAG=2.4
  

  Copy

⁠Use built plugin

• This will use the plugin, use it, and remove it

  docker volume create -d studioetrange/bindfs:latest -o sourcePath=$(pwd) -o map=$(id -u)/0:@$(id -g)/@0 test_bindfs_volume
  
  docker run --rm -it --name test_bindfs -v test_bindfs_volume:/test alpine:latest ls /test
  
  docker volume rm test_bindfs_volume
  
  make remove
  docker plugin ls
  

  Copy

⁠Debug

• Enable debug mode on the installed plugin

  make enable-debug
  

  Copy

  OR

  docker plugin disable studioetrange/bindfs:latest
  docker plugin set studioetrange/bindfs:latest DEBUG=1
  docker plugin enable studioetrange/bindfs:latest
  

  Copy

• Exec into the installed and running plugin

  # get ID of the plugin
  sudo runc --root /run/docker/runtime-runc/plugins.moby list 
  # exec shell into plugin
  sudo runc --root /run/docker/runtime-runc/plugins.moby exec -t <ID> sh
  

  Copy

• Build and launch a new container with plugin binaries inside

  make test
  # without using docker cache :
  make test-nocache
  

  Copy

⁠Publish plugin

• Publish a built plugin to docker hub

  make DOCKER_LOGIN='studioetrange' DOCKER_PASSWORD='password' PLUGIN_TAG=2.4 push
  make PLATFORM=arm64 DOCKER_LOGIN='studioetrange' DOCKER_PASSWORD='password' PLUGIN_TAG=2.4rc1 push
  

  Copy

⁠GO update version and dependency management

• GO VERSION UPDATE :

  • Edit Dockerfile and change FROM image with one from dockerhub https://hub.docker.com/_/golang/tags?page=1&name=bullseye⁠ based on debian bullseye (i.e : FROM golang:1.24.6-bullseye as gobuilder)
  • Use this version in dependencies management step

• DEPENDENCIES MANAGEMEMENT : For go 1.20+ using standard Go Modules (without govendor)

  git clone https://github.com/StudioEtrange/docker-volume-bindfs
  cd docker-volume-bindfs
  docker run -it --rm --volume=$(pwd):/go/src/github.com/StudioEtrange/docker-volume-bindfs golang:1.24.6-bullseye bash
  
  # FROM INSIDE CONTAINER
  cd /go/src/github.com/StudioEtrange/docker-volume-bindfs
  
  
  # check status of used packaged from source code
  go mod verify
  
  # INIT Go modules management
  go mod init
  
  # SYNC package between vendor content and vendor.json 
  go mod vendor
  
  # FROM OUTSIDE CONTAINER
  sudo chown -R $(id -u):$(id -g) vendor
  sudo chown -R $(id -u):$(id -g) go.mod
  sudo chown -R $(id -u):$(id -g) go.sum
  

  Copy

⁠TODO

• migrate logrus to zerolog like in docker-volume-rclone for logging purpose

  • https://github.com/rs/zerolog⁠
  • https://github.com/sapk/docker-volume-rclone/blob/master/rclone/driver/driver.go⁠

• change the path of the persistent file from /var/lib/docker/plugins to /etc/docker-volume-bindfs ?

• Protect the volume list with mutex for every driver operation :

  • https://github.com/sapk/docker-volume-rclone/blob/master/rclone/driver/driver.go⁠
  • https://github.com/fentas/docker-volume-davfs/blob/master/main.go⁠

• linux/arm64 support

⁠LICENSE

MIT