Skip to main content

Use JuiceFS in Docker

JuiceFS can be integrated with Docker Engine using volume plugin.

Install plugin

Install the plugin with the following command, grant permissions when asked.

docker plugin install juicedata/juicefs

Create Volume

Create a new volume using necessary credentials:

docker volume create -d juicedata/juicefs \
-o name=$VOL_NAME -o token=$JFS_TOKEN \
-o accesskey=$ACCESS_KEY -o secretkey=$SECRET_KEY jfsvolume

If you have trouble finding the credentials for above command, refer to Creating a file system.

Mount Volume

Mount the volume in Docker. For example

docker run -it -v jfsvolume:/jfs busybox ls /jfs

Remove Volume

docker volume remove jfsvolume

Note that:

  1. the volume must be unmounted from all usage before removing.
  2. removing the volume from Docker does NOT affect the data stored in JuiceFS

Disable and remove plugin

docker plugin disable juicedata/juicefs
docker plugin remove juicedata/juicefs

Using docker-compose

Example for creating and mounting JuiceFS volume with docker-compose

version: '3'
services:
busybox:
image: busybox
command: "ls /jfs"
volumes:
- jfsvolume:/jfs
volumes:
jfsvolume:
driver: juicedata/juicefs
driver_opts:
name: ${VOL_NAME}
token: ${JFS_TOKEN}
accesskey: ${ACCESS_KEY}
secretkey: ${SECRET_KEY}

The secrets could be passed via environment variables.

To bring up the services

docker-compose up

To shut down the service and remove docker volumes

docker-compose down --volumes

Use in Docker swarm

JuiceFS volume can be shared in Docker swarm. Make sure that volume plugin juicedata/juicefs is installed on every worker node.

Pass options to --mount to create service mounting JuiceFS volume.

docker service create --name nginx --mount \
type=volume,volume-driver=juicedata/juicefs,source=jfsvolume,destination=/jfs, \
volume-opt=name=$VOL_NAME,volume-opt=token=$JFS_TOKEN,volume-opt=accesskey=$ACCESS_KEY,volume-opt=secretkey=$SECRET_KEY nginx:alpine

Troubleshooting

If JuiceFS Docker volume plugin is not working properly, check logs to debug.

  • Collect JuiceFS logs:

    # locate the docker plugins runtime directory, your environment may differ from below example
    ls /run/docker/plugins/runtime-root/plugins.moby
    # print plugin container info
    runc --root /run/docker/plugins/runtime-root/plugins.moby list
    # cat log inside plugin container
    runc --root /run/docker/plugins/runtime-root/plugins.moby exec 452d2c0cf3fd45e73a93a2f2b00d03ed28dd2bc0c58669cca9d4039e8866f99f cat /var/log/juicefs.log

    If juicefs.log doesn't exist, this usually indicates a bad mount, check plugin logs to further debug.

  • Collect plugin log, for example under systemd:

    journalctl -f -u docker | grep "plugin="

    juicefs is called to perform the actual mount inside the plugin container, if any error occurs, it will be shown in the Docker daemon logs, same when there's error with the volume plugin itself.