Wisp is in pre-release, self-hosted since GitHub suspended us. Install it, or see the changelog.

Wisp

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 VOLUME line (Railway's builder refuses one). Mount /data with -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 HEALTHCHECK of server --health: the binary asks its own /_wisp/health and exits 0 on a 200, so the image needs no curl. The path answers 503 once the server is stopping (and through WISP_STOP_DELAY before it).
  • Starts as root with WISP_USER=65532: the server gives /data to that user (a host's volume is root's) and runs as them. Run it with --user and 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 -e or 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_enter and io_uring_register brings it back.
  • The server runs as user 65532. The image starts as root only so the server can make /data that user's (a volume mounted there, on Fly, Render or Railway, is root's), then run itself as them (WISP_USER=65532; no shell or setpriv in the image). Started as another user (docker run --user), it just runs.
  • WebSockets and streaming work.
  • docker stop sends SIGTERM and kills 10 s later, which is the server's longest drain (WISP_DRAIN, 10 s). Pass -t 15 (or stop_grace_period: 15s in 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::kv and wisp::blobs default to files under $WISP_DATA/storage, on the same volume as the tables. See Storage.

More

Deploying, Host on a VPS.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.