{"id":50531809,"url":"https://github.com/maaso/moosefs-docker-volume-plugin","last_synced_at":"2026-06-03T14:04:24.941Z","repository":{"id":222140859,"uuid":"185653873","full_name":"maaso/moosefs-docker-volume-plugin","owner":"maaso","description":"Docker volume plugin for MooseFS","archived":false,"fork":false,"pushed_at":"2022-12-08T17:45:22.000Z","size":57,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-02-12T16:19:19.932Z","etag":null,"topics":["docker","docker-plugin","moosefs","moosefs-client"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maaso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-05-08T17:48:10.000Z","updated_at":"2024-02-12T16:19:21.874Z","dependencies_parsed_at":"2024-02-12T16:29:27.580Z","dependency_job_id":null,"html_url":"https://github.com/maaso/moosefs-docker-volume-plugin","commit_stats":null,"previous_names":["maaso/moosefs-docker-volume-plugin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/maaso/moosefs-docker-volume-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maaso%2Fmoosefs-docker-volume-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maaso%2Fmoosefs-docker-volume-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maaso%2Fmoosefs-docker-volume-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maaso%2Fmoosefs-docker-volume-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maaso","download_url":"https://codeload.github.com/maaso/moosefs-docker-volume-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maaso%2Fmoosefs-docker-volume-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33867885,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-plugin","moosefs","moosefs-client"],"created_at":"2026-06-03T14:04:24.129Z","updated_at":"2026-06-03T14:04:24.933Z","avatar_url":"https://github.com/maaso.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# This repository is work-in-progress and not suited for production use\n# MooseFS Docker Plugin\n\nA Docker volume driver plugin for mounting a [MooseFS](https://moosefs.com) filesystem. Allows you to transparently provide storage for your Docker containers using MooseFS. \n## Usage\n\n### Prerequisites\n\nBefore you can use the plugin you must have:\n\n* A running MooseFS cluster that your Docker host can access.\n* A directory on the MooseFS filesystem that can be used by the plugin to store Docker volumes. This can be any normal directory. By default the plugin will use `/docker/volumes`, but this can be changed ( see [REMOTE_PATH](#remote-path) ).\n\nOnce these conditions are met you are ready to install the plugin.\n\n### Installation\n\nThe plugin is simple use and can be installed as a Docker container without having to install any other system dependencies.\n\n    $ docker plugin install --alias moosefs maaso/moosefs-volume-plugin HOST=mfsmaster PORT=9421\n\nDocker will prompt asking if you want to grant the permissions required to run the plugin. Select yes and the plugin will download and install.\n\n\u003e **Note:** We set the plugin alias to `moosefs`. This is completely optional, but it allows us to refer to the plugin with a much shorter name. Throughout this readme, when reference is made to the `moosefs` driver, it is referring to this alias.\n\nThat's it! You can now see your newly installed Docker plugin by running `docker plugin ls`.\n\n    $ docker plugin ls\n    ID                  NAME                 DESCRIPTION                         ENABLED\n    4a08a23cf2eb        moosefs:latest       MooseFS volume plugin for Docker    true\n\nYou should now be able to create a Docker volume using our new `moosefs` driver.\n\n    $ docker volume create --driver moosefs moose-vol\n    moose-vol\n\nYou can see it by running `docker volume ls`.\n\n    $ docker volume ls\n    DRIVER               VOLUME NAME\n    moosefs:latest       moose-vol\n\nNow that you have created the volume you can mount it into a container using its name. Lets mount it into an alpine container and put some data in it.\n\n```sh\n$ docker run -it --rm -v moose-vol:/data alpine sh\n/ $ cd /data # Switch to our volume mountpoint\n/data $ cp -R /etc . # Copy the whole container /etc directory to it\n/data $ ls # See that the copy was successful\netc\n/data $ exit # Exit ( the container will be removed because of the --rm )\n```\n\nWe should now have a copy of the alpine container's whole `/etc` directory on our `moose-vol` volume. You can verify this by checking the `/docker/volumes/moose-vol/` directory on your MooseFS installation. You should see the `etc` folder with all of its files and folders in it. Congratulations! You have successfully mounted your MooseFS filesytem into a docker container and stored data in it!\n\nIf you run another container, you can mount the same volume into it and that container will also see the data. Your data will stick around as long as that volume exists. When you are done with it, you can remove the volume by running `docker volume rm moose-vol`.\n\n### Features\n\n#### Shared Mounts\n\nAny number of containers on any number of hosts can mount the same volume at the same time. The only requirement is that each Docker host have the MooseFS plugin installed on it.\n\n#### Transparent Data Storage ( No Hidden Metadata )\n\nEach MooseFS Docker volume maps 1-to-1 to a directory on the MooseFS filesystem. All directories in the [REMOTE_PATH](#remote-path) on the MooseFS filesystem will be exposed as a Docker volume regardless of whether or not the directory was created by running `docker volume create`. There is no special metadata or any other extra information used by the plugin to keep track of what volumes exist. If there is a directory there, it is a Docker volume and it can be mounted ( and removed ) by the MooseFS plugin. This makes it easy to understand and allows you to manage your Docker volumes directly on the filesystem, if necessary, for things like backup and restore.\n\n#### MooseFS Global Trash Bin\n\nUsing MooseFS for your Docker volumes means that you now get the benefit of MooseFS's global trash bin. Removed files and volumes can be restored using MooseFS's [trash bin](https://docs.moosefs.com/adminguide/advanced_configuration.html?highlight=trash#mounting-the-meta-data) mechanism. Note that the plugin itself has nothing to do with this; it is a native feature of MooseFS.\n\n#### Multiple MooseFS Clusters\n\nIt is also possible, if you have multiple MooseFS clusters, to install the plugin multiple times with different settings for the different clusters. For example, if you have two MooseFS clusters, one at `mfsmaster1` and another at `mfsmaster2`, you can install the plugin two times, with different aliases, to allow you to create volumes on both clusters.\n\n    $ docker plugin install --alias moosefs1 --grant-all-permissions maaso/moosefs-volume-plugin HOST=mfsmaster1 PORT=9421\n    $ docker plugin install --alias moosefs2 --grant-all-permissions maaso/moosefs-volume-plugin HOST=mfsmaster2 PORT=9421\n\nThis gives you the ability to create volumes for both clusters by specifying either `moosefs1` or `moosefs2` as the volume driver when creating a volume.\n\n#### Root Mount Option\n\nThe plugin has the ability to provide a volume that contains *all* of the MooseFS Docker volumes in it. This is called the Root Volume and is identical to mounting the configured `REMOTE_PATH` on your MooseFS filesystem into your container. This volume does not exist by default. The Root Volume is enabled by setting the `ROOT_VOLUME_NAME` to the name that you want the volume to have. You should pick a name that does not conflict with any other volume. If there is a volume with the same name as the Root Volume, the Root Volume will take precedence over the other volume.\n\nThere are a few different uses for the Root Volume. Kadima Solutions designed the Root Volume feature to accommodate for containerized backup solutions. By mounting the Root Volume into a container that manages your Backups, you can backup *all* of your MooseFS Docker volumes without having to manually add a mount to the container every time you create a new volume that needs to be backed up.\n\nThe Root Volume also give you the ability to have containers create and remove MooseFS volumes without having to mount the Docker socket and make Docker API calls. Volumes can be added, removed, and otherwise manipulated simply by mounting the Root Volume and making the desired changes.\n\n### Known Issues\n\n#### Hangs on Unresponsive MooseFS Master\n\nIn most cases, when the plugin cannot connect to the MooseFS cluster, the plugin will timeout quickly and simply fail to create mounts or listings of volumes. However, when the plugin *has* been able to open a connection with the MooseFS master, and the MooseFS master subsequently fails to respond, a volume list operation will cause the plugin to hang for a period of time. This will cause any Docker operations that request the volume list to freeze while the plugin attempts to connect to the cluster. To fix the issue, the connectivity to the MooseFS master must be restored, otherwise the plugin should be disabled to prevent stalling the Docker daemon.\n\n## Configuration\n\n### Plugin Configuration\n\nYou can configure the plugin through plugin variables. You may set these variables at installation time by putting `VARIABLE_NAME=value` after the plugin name, or you can set them after the plugin has been installed using `docker plugin set maaso/moosefs-volume-plugin VARIABLE_NAME=value`.\n\n\u003e **Note:** When configuring the plugin after installation, the plugin must first be disabled before you can set variables. There is no danger of accidentally setting variables while the plugin is enabled, though. Docker will simply tell you that it is not possible.\n\n#### HOST\n\nThe hostname/ip address that will be used when connecting to the MooseFS master.\n\n\u003e **Note:** The plugin runs in `host` networking mode. This means that even though it is in a container, it shares its network configuration with the host and should resolve all network addresses as the host system would.\n\n**Default:** `mfsmaster`\n\n#### PORT\n\nThe port on which to connect to the MooseFS master.\n\n**Default:** `9421`\n\n#### MOUNT_OPTIONS\n\nOptions passed to the `mfsmount` command when mounting MooseFS volumes. More information can be found in the [MooseFS documentation](https://docs.moosefs.com/man/mfsmount.1.html).\n\n**Default:** empty string\n\n#### REMOTE_PATH\n\nThe path on the MooseFS filesystem that Docker volumes will be stored in. This path will be mounted for volume storage by the plugin and must exist on the MooseFS filesystem. The plugin fail to connect to the master server if the path does not exist.\n\n**Default:** `/docker/volumes`\n\n#### ROOT_VOLUME_NAME\n\nThe name of the Root Volume. If specified, a special volume will be created of the given name will be created that will contain all of the MooseFS volumes. It is equivalent to mounting the `REMOTE_PATH` on the MooseFS filesystem. See [Root Mount Option](#root-mount-option).\n\n**Default:** empty string\n\n#### CONNECT_TIMEOUT\n\nThe timeout for MooseFS mount commands. If a mount takes longer than the `CONNECT_TIMEOUT` in milliseconds, it will be terminated and the volume will not be mounted. This is to keep Docker operations from hanging in the event of an unresponsive master.\n\n**Default:** `10000`\n\n#### LOG_LEVEL\n\nPlugin logging level. Set to `DEBUG` to get more verbose log messages. Logs from Docker plugins can be found in the Docker log and will be suffixed with the plugin ID.\n\n**Default:** `INFO`\n\n### Volume Options\n\nVolume options are options that can be passed to Docker when creating a Docker volume. Volume options are set per volume, therefore setting an option for one volume does not set that option for any other volume.\n\nVolume options can be passed in on the command line by\nadding `-o OptionName=value` after the volume name. For example:\n\n    $ docker volume create -d moosefs my-volume -o StorageClass=3\n\n#### StorageClass\n\nThe storage class option can be used to set the MooseFS storage class on a newly created volume. The class can be any valid class name or number that exists on the MooseFS master. See the MooseFS [documentation](https://moosefs.com/support/#documentation) for more information.\n\nNote that even after a volume has been created and a goal has been set, it is still possible to manually change the goal of the volume directory on the MooseFS filesystem manually. For example, assuming you have mounted the MooseFS filesystem manually ( not using a docker volume ):\n\n    moosefs setgoal goal_name /mnt/mfs/docker/volumes/volume_name\n\nAlso, if you want to set a default class for all of your Docker volumes, you can manually set the class of the directory containing your docker volumes on the MooseFS filesystem ( `/docker/volumes` by default, see [REMOTE_PATH](#remote-path) ).\n\n**Default:** empty string\n\n## Development\n\nDocker plugins are made up of a `config.json` file and `rootfs` directory. The `config.json` has all of the metadata and information about the plugin that Docker needs when installing and configuring the plugin. The `rootfs` is the root filesystem of the plugin container. Unfortunately the Docker CLI doesn't allow you to create Docker plugins using a Dockerfile so we use a Makefile to automate the process of creating the plugin `rootfs` from a Dockerfile.\n\n### Building the Plugin\n\nTo build the plugin simply run `make rootfs` in the project directory.\n\n    $ make rootfs\n\nThis will build the Dockerfile, export the new Docker image's rootfs, and copy the rootfs and the config.json file to the `plugin` directory. When it is done you should have a new plugin directory with a config.json file and a rootfs folder in it.\n\n```\nplugin/\n  config.json\n  rootfs/\n```\n\nAfter that is finished you can run `make create`.\n\n    $ make create\n\nThis will install the Docker plugin from the `plugin` dirctory with the name `maaso/moosefs-volume-plugin`.\n\nFinally run `make enable` to start the plugin.\n\n    $ make enable\n\n Here is a list of the `make` targets:\n\n* **clean**: Remove the `plugin` directory\n* **config**: Copy the `config.json` file to the `plugin` directory\n* **rootfs**: Generate the plugin rootfs from the Dockerfile and put it in the `plugin` directory with the `config.json`\n* **create**: Install the plugin from the `plugin` directory\n* **enable**: Enable the plugin\n* **disable**: Disable the plugin\n* **push**: Run the `clean`, `rootfs`, `create`, and `enable` targets, and push the plugin to DockerHub\n\n### Running the tests\n\nThe automated tests for the plugin are run using a Docker-in-Docker container that creates a Dockerized MooseFS cluster to test the plugin against. When you run the test container, it will install the plugin inside the Docker-in-Docker container and proceed to create a Dockerized MooseFS cluster in it as well. A shell script is run that manipulates the plugin and runs containers to ensure the plugin behaves as is expected.\n\nBefore you can run the tests, the test Docker image must first be built. This is done by running the `build-tests.sh` script.\n\n    $ ./build-tests.sh\n\nThis will build a Docker image, `moosefs-volume-plugin_test`, using the Dockerfile in the `test` directory. After the image has been built, you can use it to run the tests against the plugin. This is done with the `run-tests.sh` script.\n\n    $ ./run-tests.sh\n\nBy default running `run-tests.sh` will install the plugin from the `plugin` directory before running the tests against it. This means that you must first build the plugin by running `make rootfs`, if you have not already done so. Alternatively, you can also run the tests against a version of the plugin from DockerHub by passing in the plugin tag as a parameter to the `run-tests.sh` script.\n\n    $ ./run-tests.sh maaso/moosefs-volume-plugin:latest\n\nThis will download the plugin from DockerHub and run the tests against that version of the plugin.\n\n### Tips \u0026 Tricks\n\nIf you don't have a fast disk on your development machine, developing Docker plugins can be somewhat tricky, because it can take some time to build and install the plugin every time you need to make a change. Here are some tricks that you can use to help maximize your development time.\n\n#### Patching the Plugin Rootfs\n\nAll of the plugin logic is in the `index.js` file. During development it can take a long time to rebuild the entire plugin every time you need to test a change to `index.js`. To get around this, it is possible to copy just that file into the installed plugin without having to reinstall the entire plugin.\n\nWhen you install a Docker plugin, it is given a plugin ID. You can see the first 12 characters of the plugin ID by running `docker plugin ls`.\n\n```\n$ docker plugin ls\nID                  NAME                                            DESCRIPTION                         ENABLED\n2f5b68535b92        maaso/moosefs-volume-plugin:latest              MooseFS volume plugin for Docker    false\n```\n\nUsing that ID you can find where the plugin's rootfs was installed. By default, it should be located in `/var/lib/docker/plugins/[pluginID]/rootfs`. For our particular plugin, the file that we need to replace is the `/project/index.js` file in the plugin's rootfs. By replacing that file with an updated version and restarting ( disabling and re-enabling ) the plugin, you can update the plugin without having to re-install it.\n\n#### Test Case Development\n\nWriting new automated test cases for the plugin can also be difficult because of the time required for the test container to start. When writing new test cases for the plugin, it may be useful to start the container and interactively run the tests. If you make a mistake that causes a test to fail, even though the plugin *is* working, you can still edit and re-run the tests without having to restart the test container completely.\n\nOnce you have built the test image using the `build-tests.sh` script, you need to run the test container as a daemon that you can exec into. We override the entrypoint of the container so that it won't run the test script as soon as it starts. We want it just to sit there and wait for us to run commands in it.\n\n    $ docker run -it --rm -d --name moosefs-test --privileged \\\n    -v $(pwd)/plugin:/plugin \\\n    -v $(pwd)/test/test-run.sh:/test-run.sh \\\n    --entrypoint=sh \\\n    moosefs-volume-plugin_test\n\n\u003e **Note:** We also mount our `test-run.sh` script into the container so that updates to the script are reflected immediately in the container.\n\nAfter the container is running we can shell into it and run the script that starts up Docker.\n\n    $ docker exec -it moosefs-test sh\n    /project # /test-environment.sh\n\nThis will start Docker, load the MooseFS image used for creating the test MooseFS environment, and install the plugin from the plugin directory. Once this is done you can run the tests.\n\n    /project # sh /test-run.sh\n\nThis will run through all of the tests. If the tests fail, you can still edit and re-run the `test-run.sh` script without having to re-install the plugin.\n\nWhen you are done writing your test cases, you can `exit` the shell and `docker stop moosefs-test`. The container will be automatically removed after it stops. You should make sure that your tests still run correctly in a completely fresh environment by rebuilding and re-running the tests using the `build-tests.sh` and `run-tests.sh` scripts.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaaso%2Fmoosefs-docker-volume-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaaso%2Fmoosefs-docker-volume-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaaso%2Fmoosefs-docker-volume-plugin/lists"}