Quickstart

This guide will get you up and running with ZeroFS in minutes. We'll cover installation, basic configuration, and mounting your first S3-backed filesystem. By the end, you'll have a fully functional filesystem that stores data in S3 while feeling like local storage.

Before you begin, ensure you have access to an S3-compatible storage service and the necessary credentials (access key ID and secret access key). For quick testing without external storage, you can use file:/// URLs to store data locally.

Installation

ZeroFS is distributed as a single static binary. Choose your installation method:

# Download the latest release for your platform
curl -LO https://github.com/Barre/ZeroFS/releases/latest/download/zerofs-pgo-multiplatform.tar.gz

# Extract the archive
tar -xzf zerofs-multiplatform.tar.gz

# Make the binary executable and move it to PATH
chmod +x zerofs-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)
sudo mv zerofs-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) /usr/local/bin/zerofs

# Clean up the archive
rm zerofs-multiplatform.tar.gz

Configuration

Set up the required environment variables for ZeroFS:

# Required: Encryption password
export ZEROFS_ENCRYPTION_PASSWORD='your-secure-password'

# Required: SlateDB cache configuration
export SLATEDB_CACHE_DIR='/var/cache/zerofs'
export SLATEDB_CACHE_SIZE_GB='10'

# Recommended: Memory cache for better performance
export ZEROFS_MEMORY_CACHE_SIZE_GB='8' # 8GB memory cache

# S3 credentials (for AWS S3)
export AWS_ACCESS_KEY_ID='your-access-key'
export AWS_SECRET_ACCESS_KEY='your-secret-key'
export AWS_DEFAULT_REGION='us-east-1'

# For custom S3-compatible endpoints (e.g., MinIO, Ceph)
export AWS_ENDPOINT='https://s3.example.com'
export AWS_ALLOW_HTTP='true' # Only if using HTTP endpoints

# Azure credentials (for Azure Blob Storage)
export AZURE_STORAGE_ACCOUNT='your-account-name'
export AZURE_STORAGE_KEY='your-account-key'

# Optional: NBD block device configuration
export ZEROFS_NBD_PORTS='10809,10810' # Comma-separated list
export ZEROFS_NBD_DEVICE_SIZES_GB='10,20' # Comma-separated list of sizes in GB

See all configuration options

Start ZeroFS

Now start ZeroFS with your S3 bucket:

# Start ZeroFS with an S3 bucket
ZEROFS_ENCRYPTION_PASSWORD='your-password' \
SLATEDB_CACHE_DIR='/var/cache/zerofs' \
SLATEDB_CACHE_SIZE_GB='10' \
ZEROFS_MEMORY_CACHE_SIZE_GB='8' \
AWS_ACCESS_KEY_ID='your-key' \
AWS_SECRET_ACCESS_KEY='your-secret' \
AWS_DEFAULT_REGION='us-east-1' \
zerofs s3://my-bucket/zerofs-data

# Start ZeroFS with Azure Blob Storage
ZEROFS_ENCRYPTION_PASSWORD='your-password' \
SLATEDB_CACHE_DIR='/var/cache/zerofs' \
SLATEDB_CACHE_SIZE_GB='10' \
ZEROFS_MEMORY_CACHE_SIZE_GB='8' \
AZURE_STORAGE_ACCOUNT='your-account' \
AZURE_STORAGE_KEY='your-key' \
zerofs azure://my-container/zerofs-data

# Quick local testing without external storage
ZEROFS_ENCRYPTION_PASSWORD='your-password' \
SLATEDB_CACHE_DIR='/var/cache/zerofs' \
SLATEDB_CACHE_SIZE_GB='10' \
ZEROFS_MEMORY_CACHE_SIZE_GB='8' \
zerofs file:///tmp/zerofs-test

# Custom S3-compatible endpoint (MinIO, Ceph, etc.)
ZEROFS_ENCRYPTION_PASSWORD='your-password' \
SLATEDB_CACHE_DIR='/var/cache/zerofs' \
SLATEDB_CACHE_SIZE_GB='10' \
ZEROFS_MEMORY_CACHE_SIZE_GB='8' \
AWS_ACCESS_KEY_ID='your-key' \
AWS_SECRET_ACCESS_KEY='your-secret' \
AWS_ENDPOINT='https://minio.example.com' \
zerofs s3://my-bucket/zerofs-data

Mount the Filesystem

With ZeroFS running, mount it using standard NFS tools. Linux users can also use 9P for better performance:

# Create mount point
sudo mkdir -p /mnt/zerofs

# Mount ZeroFS
sudo mount -t nfs -o async,nolocks,vers=3,tcp,port=2049,mountport=2049 127.0.0.1:/ /mnt/zerofs

Using NBD Block Devices

If you enabled NBD support, you can also access ZeroFS as block devices:

# Install nbd-client if needed
sudo apt-get install nbd-client  # Debian/Ubuntu
sudo yum install nbd              # RHEL/CentOS

# Connect to NBD device with optimal settings
sudo nbd-client 127.0.0.1 10809 /dev/nbd0 -N device_10809 -persist -timeout 60 -block-size 4096 -connections 4

# Create filesystem
sudo mkfs.ext4 /dev/nbd0

# Mount the block device
sudo mkdir -p /mnt/nbd0
sudo mount /dev/nbd0 /mnt/nbd0

Learn more about NBD devices

Verify It's Working

Test your new filesystem:

# Check mount
df -h /mnt/zerofs

# Create a test file
echo "Hello from ZeroFS!" > /mnt/zerofs/test.txt

# Read it back
cat /mnt/zerofs/test.txt

# Check file metadata
ls -la /mnt/zerofs/

Learn about NFS operations

What's Next?

Congratulations! You now have a fully functional filesystem backed by S3. Here are some next steps:

Configure NBD block devices for raw block storage
Learn about encryption and how your data is protected
Optimize performance with caching configuration
Explore advanced architectures like geo-distributed storage