Prerequisites

• Linux host with /dev/fuse available
• Docker installed
• SYS_ADMIN capability required on the host instance
• Not supported on AWS Fargate; use EC2-backed ECS/EKS, ECS Anywhere, or a self-managed Kubernetes node
• For io_uring support: Linux kernel 6.18 or later required

Docker Image Address

Step 1: Pull the Image

docker pull [709825985650.dkr.ecr.us-east-1.amazonaws.com/]wyflow/mapfs:2.4.0

Step 2: Import Your Mapfs License

docker run --rm -v /etc/mapfs:/etc/mapfs \
  [709825985650.dkr.ecr.us-east-1.amazonaws.com/]wyflow/mapfs:2.4.0 \
  mapfs license import <email> <token>

Get your email and token from https://mapfs.cloud/

Step 3: Add a Volume (Configure Your Cloud Storage Backend)

docker run --rm -v /etc/mapfs:/etc/mapfs \
  -v <CacheDir>:<CacheDir> \
  [709825985650.dkr.ecr.us-east-1.amazonaws.com/]wyflow/mapfs:2.4.0 \
  mapfs add <VolumeName> <CloudOptions> <CacheOptions>

Note: The directory used for <CacheDir> must already exist. Docker will not create it automatically.

Example (S3-compatible):

docker run --rm -v /etc/mapfs:/etc/mapfs \
  -v /var/cache/mapfs/my-volume:/var/cache/mapfs/my-volume \
  [709825985650.dkr.ecr.us-east-1.amazonaws.com/]wyflow/mapfs:2.4.0 \
  mapfs add my-volume S3Compatible -i <AccessKeyID> -k <SecretAccessKey> \
  -b <bucket> -e <endpoint> -d /var/cache/mapfs/my-volume -z 1

Step 4: Start Channel Server [Optional if there is alreay one ChannelServer running]

docker run --rm -d \
	--name channeld \
	-p 7777:7777 \
	[709825985650.dkr.ecr.us-east-1.amazonaws.com/]wyflow/mapfs:2.4.0 channeld start

Step 5: Mount the Volume

docker run --rm -d \
  --name mapfs-<VolumeName> \
  -v /etc/mapfs:/etc/mapfs:ro \
  -v /etc/os-release:/etc/os-release:ro \
  -v <CacheDir>:<CacheDir> \
  -v /var/run/mapfs:/var/run/mapfs \
  -v /proc/meminfo:/proc/meminfo:ro \
  [-v /sys/module/fuse/parameters/enable_uring:/sys/module/fuse/parameters/enable_uring] \
  -v <MountPoint>:<MountPoint>:shared \
  --device /dev/fuse \
  --cap-add SYS_ADMIN \
  [709825985650.dkr.ecr.us-east-1.amazonaws.com/]wyflow/mapfs:2.4.0 \
  mapfs mount <VolumeName> <MountPoint> [--channel IP|DNS[:Port]] [--iouring]

Note: The [-v /sys/module/fuse/parameters/enable_uring] mount and [iouring] argument only work on Linux kernel 6.18+; omit both otherwise.

Step 6: Check Status / Logs

docker run --rm -v /var/run/mapfs:/var/run/mapfs:ro \
  [709825985650.dkr.ecr.us-east-1.amazonaws.com/]wyflow/mapfs:2.4.0 stat

docker logs -f mapfs-<VolumeName>

tail -f <CacheDir>/mapfs.log

Step 7: Unmount

docker stop mapfs-<VolumeName>

Full Documentation

For additional commands including listing/deleting volumes and configuring cache parameters, see:
https://mapfs.cloud/docs/docker/commands.html

Support

support@mapfs.cloud