Docker

The blixtfs/standard image contains everything a single-node deployment needs: the BlixtFS servers, an embedded PostgreSQL database, and the NFS and SMB gateways. The blixtfs/enterprise image adds built-in Prometheus and Grafana.

Before you begin

• A host that meets the requirements, with Docker installed.
• A bucket and working credentials. See Cloud credentials.
• A directory on the host for BlixtFS’s data, ideally on its own disk. This guide uses /srv/blixt.

Build your command

Fill in your bucket and paths, and the commands below update as you type.

Everything on one command

Good for a first run and for throwaway containers.

Or with a configuration file

A deployment you mean to keep is easier to manage as a file. Save this as config.yaml in your data directory, where the container reads it as /data/config.yaml:

The command then carries the mounts and nothing else:

Settings are read from the file first, then the environment, then the command line, so each layer overrides the one before it. That is the escape hatch for secrets: leave the R2 or CoreWeave keys out of the file and pass them with -e CLOUDFLARE_ACCESS_KEY=... on the command instead. A file that does hold them is worth a chmod 600 and a place outside version control.

Step by step

1. Pull the image

docker pull blixtfs/standard:2.9.0

The image supports both amd64 and arm64 hosts.

2. Write a configuration file

Create /srv/blixt/config.yaml. The container sees this directory as /data, so the file appears at /data/config.yaml.

general:
  default_cloud: aws

cloud:
  aws:
    enabled: true
    credentials: /credentials
    buckets:
      - bucket: s3://my-bucket
        region: us-east-1        # the bucket's real region

Serve buckets from several providers by adding a section for each: gcp, azure, oracle, minio, cloudflare or coreweave. See Configuration for the full format.

3. Start the container

docker run -d --name blixt \
  --restart unless-stopped \
  --privileged \
  -p 2049:2049 \
  -p 445:445 \
  -v /srv/blixt:/data \
  -v ~/.aws/credentials:/credentials:ro \
  -e AUTH_TOKEN="$(openssl rand -hex 32)" \
  blixtfs/standard:2.9.0 --config /data/config.yaml

What each option does:

For a quick test, you can also skip the configuration file and name buckets on the command line:

docker run -d --name blixt --privileged -p 2049:2049 \
  -v /srv/blixt:/data \
  -v ~/.aws/credentials:/config/aws/credentials:ro \
  blixtfs/standard:2.9.0 --aws_default_region us-east-1 --default_cloud aws s3://my-bucket

Without a configuration file, the container looks for credentials in /config/aws/credentials (AWS) and /config/gcp/credentials.json (Google Cloud), or at the path given by --aws_credentials or --gcp_credentials.

4. Check that it started

docker logs -f blixt

Look for the version banner and for each bucket being served. The first time BlixtFS serves a bucket it indexes it, which takes a while for buckets with millions of objects. Mark such buckets lazy to serve them straight away.

5. Mount it

# Linux
sudo mkdir -p /mnt/blixt
sudo mount -t nfs -o vers=4 localhost:/ /mnt/blixt

# MacOS
mkdir -p ~/blixt
sudo mount -t nfs -o vers=4,noresvport localhost:/ ~/blixt

ls /mnt/blixt/aws/my-bucket

The mount root has one directory per cloud provider, with your buckets inside. See Connecting clients for SMB, SFTP and remote clients.

Docker Compose

The same deployment as a Compose file. Save it as compose.yaml next to a data/ directory that holds config.yaml:

services:
  blixtfs:
    image: docker.io/blixtfs/standard:2.9.0
    container_name: blixtfs
    restart: unless-stopped
    privileged: true
    ports:
      - "127.0.0.1:2049:2049"   # NFS
      # - "127.0.0.1:445:445"   # SMB (conflicts with MacOS File Sharing)
    volumes:
      - ./data:/data
    environment:
      AUTH_TOKEN: "${AUTH_TOKEN:-}"
      LICENSE: "${LICENSE:-}"
    command: ["--config", "/data/config.yaml"]
    healthcheck:
      test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/4711"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s

docker compose up -d

The ports are bound to 127.0.0.1, so only the host itself can mount. Change them to 0.0.0.0 (or a specific interface) when other machines need access.

Enterprise edition

Use the blixtfs/enterprise image and pass your license:

docker run -d --name blixt --privileged \
  -p 2049:2049 -p 445:445 -p 3000:3000 -p 9090:9090 \
  -v /srv/blixt:/data \
  -v /srv/blixt-license:/license:ro \
  -e LICENSE=/license/blixt.license \
  blixtfs/enterprise:2.9.0 --config /data/config.yaml

Grafana is then available on port 3000 and Prometheus on port 9090. See Monitoring.

NFSv3

NFSv3 is generally discouraged compared to NFSv4. See REF Nfsv3 needs a license. It also needs host networking, because NFSv3 uses additional ports for its mount and lock protocols. Host networking works on Linux only:

docker run -d --name blixt --privileged --network host \
  -v /srv/blixt:/data -e LICENSE=... \
  blixtfs/enterprise:2.9.0 --config /data/config.yaml

Stopping and upgrading

docker stop blixt       # stops serving; pending uploads resume on the next start
docker rm blixt
docker pull blixtfs/standard:2.9.1
# ...then run the same docker run command with the new tag

Everything BlixtFS needs is in /srv/blixt and in your bucket, so replacing the container is safe. See Upgrading.