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

Wisp

Host on Fly.io

Fly.io runs containers on machines it starts for you. Wisp builds the Dockerfile as it is.

Build

wisp deploy init fly       # fly.toml, and a Dockerfile if there is none

The image build has no wisp command. So the command also runs the asset build, and changes .gitignore to keep .wisp/app.css, .wisp/npm, .wisp/img and .wisp/fonts in git (the rest of .wisp/ stays out). Commit them, and run wisp build again after you change styles, images, fonts or NPM imports.

This writes fly.toml and the same Dockerfile as wisp deploy init docker. The app name in it is your package name and must be unique on Fly. --force replaces the file. What fly.toml sets:

  • Internal port 3000, force_https, machines that stop when idle and start on a request, 256 MB and one shared CPU.
  • kill_timeout = 15. Fly sends the signal and kills 5 s later by default, while the server drains for up to 10 s.
  • [env] WISP_CLIENT_IP_HEADER = "fly-client-ip". Fly's proxy sets that header to the visitor's address, so cx.client_ip() and the rate limits see visitors, not the proxy.
  • An [[http_service.checks]] on /_wisp/health, which answers 503 once the server is stopping.
  • A 1 GB [mounts] volume named data at /data, where saved tables live. A Machine's own disk is rebuilt from the image on each start. The Dockerfile's entrypoint makes the mounted volume writable by the nobody the server runs as.

Deploy

fly launch --copy-config --no-deploy
fly secrets set WISP_SECRET=<32 or more random characters>
fly deploy --ha=false

--ha=false keeps one Machine. A volume belongs to one Machine, so a second one would get its own empty /data and its own rows.

Environment

  • WISP_SECRET as a Fly secret (above), for an app that signs cookies.
  • Other variables: Environment variables.

Regions

Fly sets FLY_REGION on each Machine, and primary_region sets PRIMARY_REGION. To serve reads near visitors and write in one place, send each write to the primary region. Have the action answer with a fly-replay: region=<primary> header when FLY_REGION is not the primary. Fly's proxy then runs the same request again there (dynamic request routing):

let here = std::env::var("FLY_REGION").unwrap_or_default();
let primary = std::env::var("PRIMARY_REGION").unwrap_or_default();
if here != primary {
    return Response::empty(409).with_header("fly-replay", format!("region={primary}"));
}

The status is not sent to the visitor: Fly replays the request instead. A request over 1 MB cannot be replayed. Saved tables still live in one Machine's volume, so rows in more than one region need a shared store (Where rows are kept).

Limits

  • The image is the Docker one: epoll instead of io_uring under Docker's default profile.
  • WebSockets and streaming work, as in any container.

Files and Data

  • static/ and the styles are inside the binary.
  • Saved tables live in the data volume at /data, on one Machine. To run more than one Machine, give the tables a shared store first (Where rows are kept).
  • wisp::kv and wisp::blobs default to files under $WISP_DATA/storage, on the /data volume when there is one. See Storage.

More

Host with Docker, Deploying.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.