Host with Docker
Docker packages the binary in a small image that runs on your machine or any container host. WebSockets, streaming and saved tables all work.
Build
wisp deploy init docker # --force replaces existing files
docker build -t my-app .
wisp deploy init docker writes a Dockerfile and a .dockerignore. The Dockerfile builds on rust:1.98-slim-trixie and runs on distroless gcr.io/distroless/cc-debian13, with HOST=0.0.0.0, PORT=3000 and WISP_DATA=/data. The .dockerignore (it keeps .env and .env.* out of the image; wisp new also lists them in .gitignore). Files that exist are left alone unless you pass --force; the Dockerfile you have is the one that is built.
The Dockerfile:
- Builds the dependencies in a layer of their own with cargo-chef, so a rebuild that changes only your code compiles only your code. It uses no cache mounts, because Railway accepts only mounts keyed by its service id.
- Pins its base images. Bump them when you move to a newer Rust.
- Has no
VOLUMEline (Railway's builder refuses one). Mount/datawith-v, or with the host's own volume. - Runs on distroless (
gcr.io/distroless/cc-debian13): glibc, CA certificates and the server, no shell. - Has a
HEALTHCHECKofserver --health: the binary asks its own/_wisp/healthand exits 0 on a 200, so the image needs no curl. The path answers 503 once the server is stopping (and throughWISP_STOP_DELAYbefore it). - Starts as root with
WISP_USER=65532: the server gives/datato that user (a host's volume is root's) and runs as them. Run it with--userand it just runs.
For a Tor onion service, wisp deploy init docker --onion also writes a docker-compose.yml with a Tor container in front of the app, tor.Dockerfile and torrc, and sets WISP_ONION=on in the image.
Deploy
docker run -p 3000:3000 -e WISP_SECRET=... -v my-app-data:/data my-app
Fly.io, Railway, Render, Cloud Run and Azure Container Apps build the Dockerfile as it is: Fly.io, Railway, Render, Cloud Run, Azure.
Environment
WISP_SECRET: 32 or more random characters, needed by an app that signs cookies. Pass it with-eor an env file.- Other variables: Environment variables.
Limits
- Docker's default seccomp profile refuses io_uring, so the server uses an epoll loop per worker. A profile allowing
io_uring_setup,io_uring_enterandio_uring_registerbrings it back. - The server runs as user 65532. The image starts as root only so the server can make
/datathat user's (a volume mounted there, on Fly, Render or Railway, is root's), then run itself as them (WISP_USER=65532; no shell orsetprivin the image). Started as another user (docker run --user), it just runs. - WebSockets and streaming work.
docker stopsends SIGTERM and kills 10 s later, which is the server's longest drain (WISP_DRAIN, 10 s). Pass-t 15(orstop_grace_period: 15sin compose) to give it room.
Files and Data
static/and the styles are inside the binary.- Saved tables live in
/data: mount a volume there (-v my-app-data:/data) or they go with the container. See Where rows are kept. wisp::kvandwisp::blobsdefault to files under$WISP_DATA/storage, on the same volume as the tables. See Storage.
More
Is This Page Useful?