Self-hosting

Running the server

Run driftlessd with Docker or directly, where its data lives, and the available flags.

One binary, two surfaces

The server is a single program, driftlessd. It serves the client sync API under /v1 and the web admin under /admin from the same address. There is no database server or cache to run alongside it.

Run with Docker

The recommended way to run Driftless is the bundled Compose file:

docker compose up --build

This builds the image and starts the container with port 8080 published and a named volume mounted at /data. The image is built locally from the repository; it is not yet published to a registry.

Run directly

You can also run the server without Docker. Build the embedded admin UI once, then start the server:

npm --prefix web install
npm --prefix web run build
go run ./cmd/driftlessd

By default it listens on :8080 and writes data to ./data.

Flags and environment

Each flag falls back to an environment variable when it is not given on the command line, so the container can be configured entirely through the environment:

-data DIR / DRIFTLESS_DATA — directory for the database and chunk store. Default ./data (the container uses /data).
-addr ADDRESS / DRIFTLESS_ADDR — listen address. Default :8080.

A flag given explicitly on the command line wins over the environment variable.

Health checks

The server answers GET /healthz without authentication. It returns 200 with the body ok when the database is reachable and 503 otherwise, so it can back a Docker HEALTHCHECK or an orchestrator's liveness and readiness probes.

What is stored, and backups

Inside the data directory you will find a SQLite database (users, tokens, file versions, and the chunk index) and a content-addressed blob store holding the file chunks. To back up a Driftless server, back up the whole data directory — or, under Docker, the driftless-data volume. A consistent copy taken while the server is stopped is simplest.

Adding users from the command line

Besides the admin UI, you can create a sync user with the adduser subcommand. The password is read from standard input:

driftlessd adduser -data /data alice

Stopping and restarting

On SIGINT or SIGTERM the server stops accepting new connections and lets in-flight requests finish before exiting; a live event stream is closed immediately so shutdown does not stall. docker compose stop and docker compose restart trigger this clean shutdown, and a second signal exits at once.

Upgrades

To upgrade, rebuild or pull the new image and restart. The database schema is versioned and migrations run automatically on startup, so pointing a newer server at an existing data directory is expected to work.