Docker
Run BlixtFS as a single container on any host with Docker. This is the quickest way to a production-ready single-node deployment.
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.