Blixt Documentation v2.11

The blixtfs/standard image contains everything a single-node deployment needs: the BlixtFS servers, an embedded 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.
  • Somewhere for BlixtFS’s data. This guide uses a Docker volume named blixt-data. A host directory works too: see Where the data lives.

Build your command

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

Cloudflare R2 credentials
CoreWeave credentials

Nothing you type here leaves your browser: the commands below are assembled on this page.

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 the directory you run the command from. The container reads it as /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:latest

The image supports both amd64 and arm64 hosts.

2. Create a data volume

docker volume create blixt-data

BlixtFS keeps its index, cache, staged writes and logs in this volume. It outlives the container, so an upgrade or a docker rm keeps your data. docker run would create the volume on first use anyway, but creating it first makes it plain where the data lives. docker volume inspect blixt-data shows where Docker stores it.

To keep the data in a directory of your choosing instead, skip this step and see Where the data lives.

3. Write a configuration file

Create /etc/blixt/config.yaml. The container is given this one file, read-only, as /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.

4. Start the container

docker run -d --name blixt \
  --log-driver json-file --log-opt max-size=10m --log-opt max-file=5 \
  --restart unless-stopped \
  --privileged \
  -p 2049:2049 \
  -p 445:445 \
  -v blixt-data:/data \
  -v /etc/blixt/config.yaml:/config.yaml:ro \
  -v ~/.aws/credentials:/credentials:ro \
  -e AUTH_TOKEN="$(openssl rand -hex 32)" \
  blixtfs/standard:2.11.0 --config /config.yaml

What each option does:

Option Purpose
--log-driver … --log-opt … Limits what Docker keeps of the container’s output to 50 MB. Without a limit it grows until the disk is full.
--privileged Lets the embedded NFS server bind its ports and run its helpers.
-p 2049:2049 NFS.
-p 445:445 SMB. Leave it out on MacOS if File Sharing is enabled, because MacOS already uses port 445.
-v blixt-data:/data Database, cache, write staging and logs, in a Docker volume. It must be a volume or a host directory, never the container’s own filesystem. See Where the data lives.
-v …:/config.yaml:ro Your configuration file, read-only.
-v …:/credentials:ro Your cloud credentials file, read-only.
-e AUTH_TOKEN=… Token that BlixtFS’s internal services use to authenticate each other.

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 \
  --log-driver json-file --log-opt max-size=10m --log-opt max-file=5 \
  -v blixt-data:/data \
  -v ~/.aws/credentials:/config/aws/credentials:ro \
  blixtfs/standard:2.11.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.

5. 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.

To limit the output of every container on the host instead of naming the options on each command, set the defaults in /etc/docker/daemon.json and restart Docker. They apply to containers created after that:

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "5" }
}

6. 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.

Where the data lives

Everything BlixtFS keeps locally is under /data in the container: the metadata index (an embedded database), writes staged for upload, the read cache and the logs. It has to outlive the container, so /data must be a Docker volume or a host directory. BlixtFS refuses to start when it is neither.

A Docker volume is recommended, as in the examples on this page:

-v blixt-data:/data

Docker creates the volume on first use and keeps it until you remove it with docker volume rm blixt-data.

A host directory works too:

-v /srv/blixt:/data

Use one when you want the data somewhere specific, such as on a disk of its own, or want to reach the files from the host. The embedded database has to own its data directory, so BlixtFS changes the owner that directory. The host’s filesystem has to allow that, which not every Docker host’s does: see Known issues.

Docker Compose

The same deployment as a Compose file. Save it as compose.yaml next to config.yaml:

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

volumes:
  blixt-data:
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 \
  --log-driver json-file --log-opt max-size=10m --log-opt max-file=5 \
  -p 2049:2049 -p 445:445 -p 3000:3000 -p 9090:9090 \
  -v blixt-data:/data \
  -v /etc/blixt/config.yaml:/config.yaml:ro \
  -v /srv/blixt-license:/license:ro \
  -e LICENSE=/license/blixt.license \
  blixtfs/enterprise:latest --config /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 \
  --log-driver json-file --log-opt max-size=10m --log-opt max-file=5 \
  -v blixt-data:/data -v /etc/blixt/config.yaml:/config.yaml:ro \
  -e LICENSE=... \
  blixtfs/enterprise:latest --config /config.yaml

Stopping and upgrading

docker stop -t 90 blixt   # waits up to 60s for pending uploads, then stops
docker rm blixt
docker pull blixtfs/standard:latest
# ...then run the same docker run command with the new tag

On docker stop, BlixtFS stops serving and then waits for writes that are staged but not yet uploaded to reach the bucket, for up to file.shutdown_drain_seconds (default 60). Docker’s own default is to kill a container 10 seconds after asking it to stop, so pass -t with a value above that setting. With Docker Compose, set stop_grace_period: 90s on the service.

Uploads still pending when it stops are not lost: they resume on the next start with the same /data. Everything BlixtFS needs is in /data, your configuration file and your bucket, so replacing the container is safe. See Upgrading.

Known issues

OrbStack: a host directory cannot hold /data

On OrbStack, a host directory mounted at /data stops BlixtFS at startup. OrbStack’s host directories report every file as owned by root and silently ignore changes of owner, so the embedded database cannot own its data directory: The database refuses to run with a data directory owned by root. The log says:

/data/index/postgres is still owned by 0:0 after chown to postgres (103:104).

Use a Docker volume, as in the examples on this page: -v blixt-data:/data. Docker Desktop’s host directories keep ownership, so they work.