Deploying
Run wisp build, copy the binary, run it. Pick the build for your host:
| You have | Use |
|---|---|
| VPS or server | wisp host sets it up and keeps it running (Wisp Host). Or wisp build, then wisp service install (VPS) |
| Container host (Fly.io, Railway, Render, Cloud Run, Azure) | wisp deploy init docker (Docker) |
| Static host (GitHub Pages, GitLab Pages, S3) | wisp build --static (or --spa) |
| Edge or serverless (Cloudflare, Deno Deploy, Vercel, Netlify, Amplify, Firebase, Azure Static Web Apps) | wisp build --target <host> (Edge and serverless targets) |
| AWS Lambda / Bun / Node | --target lambda / --target bun / --target node |
An app that signs cookies (sign-ins, signed cookies, tokens, OAuth) needs WISP_SECRET (32+ random characters, for example openssl rand -hex 32) on every host. A release server whose app signs does not start without it; if the build could not tell, the server logs once and refuses signed things until it is set. Logs and metrics: Observe. Per host: Hosting.
In a host's CI a plain wisp build picks the target from its variables and says so: WORKERS_CI (cloudflare), CF_PAGES (pages), VERCEL (output in .vercel/output), NETLIFY, DENO_DEPLOYMENT_ID (deno), AWS_APP_ID (node). --target native forces the binary.
wisp deploy init <host> writes a config:
| Host | Writes |
|---|---|
cloudflare, cloudflare-pages, deno, vercel, netlify, lambda, pages (GitHub Pages) | .github/workflows/deploy.yml: build and deploy on push to main. Line 1 names the secrets; --force replaces it. cloudflare and cloudflare-pages also write a wrangler.toml when there is no Wrangler config (Your wrangler config) |
fly, render, railway, cloud-run | that host's config, and a Dockerfile if none |
docker | a Dockerfile (--onion: Tor) |
tor | torrc and env for Tor (--unix: socket) |
node and bun are servers for hosts that run npm start or a container.
Binary
wisp build makes one release binary with static files and styles inside. It listens on $HOST:$PORT (0.0.0.0:3000 in release).
The h2 feature serves h2c with prior knowledge on the same port (for a proxy that speaks h2c); WebSockets work over it. There is no TLS.
# Cargo.toml
wisp = { version = "..", features = ["h2"] }
Behind a reverse proxy: TLS, HTTP/2, HTTP/3
Wisp has no built-in HTTPS or ACME. Put Caddy or nginx in front; the proxy talks plain HTTP/1.1 to Wisp on the same machine. Bind Wisp to loopback so only the proxy reaches it, and tell it what the proxy tells the visitor:
HOST=127.0.0.1 PORT=3000 ORIGIN=https://example.com SITE_URL=https://example.com WISP_CLIENT_IP_HEADER=x-forwarded-for WISP_HSTS=on ./app
Wisp reads these headers from the proxy and no others:
| Header | Used for |
|---|---|
x-forwarded-proto | HTTPS or not: Secure cookies, WISP_HSTS, absolute links when SITE_URL is unset. The last value counts (WISP_CLIENT_IP_DEPTH from the right), the one the proxy added. Believed only when WISP_CLIENT_IP_HEADER is set; cookies are Secure anyway except for plain http to localhost or loopback, so a plain-http deploy reached by another name needs a proxy that sends x-forwarded-proto: http (with WISP_CLIENT_IP_HEADER), else sign-in fails (logged once) |
x-forwarded-host | the host the visitor typed, for the form-post same-site check (with ORIGIN) and absolute links |
the header named by WISP_CLIENT_IP_HEADER | the client address (cx.client_ip(), rate limits). The last address counts. Unset, the client is the proxy |
There is no trusted-proxy list: only the proxy may reach Wisp (loopback, firewall or private network). ORIGIN is the address visitors type, with no path.
Caddy
Caddy gets a certificate itself and serves HTTP/2 and HTTP/3 (open UDP 443 too). It replaces any X-Forwarded-* the visitor sent; header_up adds X-Real-IP. Run the app with WISP_CLIENT_IP_HEADER=x-real-ip.
example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000 {
header_up X-Real-IP {remote_host}
}
}
encode is optional; Wisp serves its embedded files as brotli (made at build time) or gzip, and gzips COMPRESS routes (Serve extras).
nginx
nginx needs the headers spelled out and a certificate. HTTP/3 needs nginx 1.25+ built with QUIC.
map $http_upgrade $connection_upgrade { default upgrade; '' close; }
server {
listen 443 ssl;
listen 443 quic reuseport;
http2 on;
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
add_header Alt-Svc 'h3=":443"; ma=86400' always;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_buffering off;
proxy_read_timeout 1h;
}
}
server {
listen 80;
server_name example.com;
return 301 https://$host$request_uri;
}
proxy_buffering off lets streams and live updates through as written, Upgrade is for WebSockets, and proxy_read_timeout 1h keeps a quiet event stream open. Run the app with WISP_CLIENT_IP_HEADER=x-real-ip.
Unix socket
A proxy on the same machine can reach the app over a Unix-domain socket instead of a TCP port: run it with WISP_LISTEN=unix:/run/app/app.sock and point the proxy at the socket (nginx proxy_pass http://unix:/run/app/app.sock;, Caddy reverse_proxy unix//run/app/app.sock). It prints wisp: listening on unix:<path>, replaces a socket file left by an earlier run (nobody answers on it), refuses to replace a live server's socket or any other file, and removes its own socket on stop (a killed run leaves one, which the next start replaces). It serves HTTP/1.1 on tokio's driver on Linux and macOS, not the io_uring or epoll ones, and takes no WebSocket upgrades. A WebSocket upgrade logs WebSockets need a TCP listener, not WISP_LISTEN=unix: and closes the connection. Every peer reads as 0.0.0.0, so set WISP_CLIENT_IP_HEADER (here x-real-ip) or rate limits by client IP count all visitors as one. The socket is created with the process's umask, so under the usual 022 only its own user can connect: run the proxy as that user, or give both a group and start the app with umask 002 (systemd UMask=0002) in a directory the group can enter. server --health probes PORT and so does not see the socket; check it with curl --unix-socket /run/app/app.sock http://x/_wisp/health.
Static and SPA
wisp build --static [--out site] writes dist/, each parameterless page as about/index.html. Each head inlines the CSS rules its markup can match, and the whole minified sheet loads at the end of the body as a low-priority <link>. --spa and prerendered pages get the same. --static and PRERENDER skip a guarded page (SIGNED_IN or MIDDLEWARE on the page or a layout): a file has no guard. --static prints a warning. It skips a link to a guarded page, with no dead-link error. A guard you write in code (a before hook or a load that redirects) does not count: use SIGNED_IN or MIDDLEWARE. Under a CSP whose style-src (else default-src) lacks 'unsafe-inline' or has a nonce or hash, nothing is inlined.
The export also writes static/ and the /_app files (.maps with --sourcemap). Forms need a server, and the export warns for each page with actions or a posting form. A [params] route lists its pages in src/routes/blog/[slug]/+page.wisp (or its +page.rs):
---
fn entries() -> Vec<&'static str> {
vec!["hello", "second-post"]
}
---
entriesreturns aStringor&strper param, or a tuple in path order. An empty string leaves out an optional or rest param.- A route with actions or a
+server.rsneeds a server (the export warns). dist/_headers(Netlify, Cloudflare Pages) holds the pages' security headers (the CSP,x-content-type-options,referrer-policy, andstrict-transport-securitywhen built withWISP_HSTS=on), theheaders = [...]rules ofCargo.toml(/api/[id]becomes/api/:id,[...p]becomes*), and cache rules: versioned/_app/files,/_app/img/*and/_app/c/npm/*are immutable for a year, while/_app/c/el/*and source maps revalidate.- Cloudflare Pages reads only the first 100 rules (not measured here). Past that,
wisp buildwarnswarn _headers: N versioned files past Cloudflare Pages' 100 rules keep the host's default cache. Your ownstatic/_headersgoes first and counts against the 100. Wisp does not write again a header your file sets on a pattern (one CSP, not two). A file whoseCache-Controlyour file or aheadersrule sets gets none of the generated cache rules. --staticbuilds withWISP_STATIC=1. A plaincargo build --releaseleaves the exporter out and stops with a message underWISP_EXPORT; setWISP_STATIC=1to run the export yourself. Run the binary from the app folder:WISP_EXPORTwrites its file list in.wisp/of the working directory.--spais--staticplus anindex.htmlfallback for routes the browser draws. It writes_redirects(Netlify, Cloudflare Pages),vercel.jsonrewrites and a404.htmlshell (GitHub Pages), and keeps your own files (see Static Export).- A
const SSR: bool = false;page whose[params]have noentriesis written once to_app/spa/N.html. wisp.js draws the one whose route fits, soroute.paramsandload({ params })hold the address's params. Each page loads/_app/c/spa.js(about 1.7 KB gzipped), which prefetches those pages.
Speed
_headers caches each versioned /_app/ file for a year. Images get width/height and loading="lazy" (fetchpriority="high" and <img priority> skip the lazy). The router fetches a link's page ahead on hover, touch, press and keyboard focus. Release builds minify src/lib and component modules.
A stale-while-revalidate rule of your own can show a page one deploy old that names the old build's /_app/ files, so keep those reachable. Behind Cloudflare, turn off Rocket Loader, which breaks scripts on swapped-in pages.
cargo run -q -p wisp-gate site (in the Wisp repo, with this site at ../wisp-docs or WISP_DOCS_DIR) builds this site with wisp build --static; the full gate does too (fast skips it). The site checkout must be on main. A default ../wisp-docs on another branch fails the step. It prints the path, the HEAD and "set WISP_DOCS_DIR to the docs checkout on main". An explicit WISP_DOCS_DIR on another branch fails the audit and stamps steps. The speed budgets still run and print a line about the branch. The speed gate fails on a page over budget, a render-blocking <script src> in <head>, a dead file link, or an <img> without width and height. Budgets: HTML 20,365 B (21,200 B for the benchmarks page), critical CSS in the head 8,500 B (9,180 B for the examples pages and 9,650 B for the home page), linked CSS 30,500 B, scripts and module preloads 47,000 B, preloaded fonts 108,000 B. The HTML budget counts a changelog version page without its release body (the <article> element). The body has its own ceilings: 29,800 B and 11,450 B gzipped. The pages of the unreleased changes have the same ceilings. The consts at the top of tests/gate/src/site.rs in the Wisp repo set them. cargo run -q -p wisp-gate site --dist <folder> checks a site that is already built in <folder> against the same budgets. It builds nothing and needs no docs checkout.
Lighthouse is a hand check: npx --yes lighthouse@12.8.2 http://localhost:8080/docs/ --form-factor=mobile --only-categories=performance, median of three runs.
Prerender
---
const PRERENDER: bool = true;
// with [params]
fn entries() -> Vec<&'static str> {
vec!["hello", "second-post"]
}
let post = db::post(&slug).await?;
---
wisp buildbuilds the binary, runs it once (initruns) to render those pages, builds again with the bytes inside, and serves them as they are (ETag, 304).- One render serves all, so
cxin statements, markup orloadis a build error. Layouts render once, as for a request without cookies. - The crawl, as SvelteKit's
prerender.crawl: the<a href>,<link href>(not resource hints) and<img src>of each prerendered page are followed (not inside comments,<script>,<style>or<template>), query and fragment dropped, other hosts and schemes left out. The app's router (matchers included) names the route of each link. APRERENDERroute renders the page and its links are followed in turn, so a[slug]route needs noentries()when a prerendered page links to its pages. A route that is not prerendered is the server's: not fetched. Astatic/file or built asset is fetched and is fine. The crawl sends aGETto each page it follows, so aGETroute that changes data runs at build time. At most 10000 pages. APRERENDERroute with parameters, noentries()and no page found gets a warning. - A link that answers 400 or more fails the build:
error /blog links to /blog/gone, which answered 404, thenN dead links. Fix them, or build with --allow-dead-links to only warn.wisp build --allow-dead-links(orWISP_DEAD_LINKS=warn) only warns. - A link with a fragment to a page that the build wrote must name an
idof that page, or thenameof an<a>there:error /blog links to /blog/hello#intro, but no element has the id intro. A fragment of the own page (#intro) counts too.#topand an empty fragment pass. The build does not check a link to a page that it did not write. The same flag and variable only warn.wisp build --no-crawlfollows no link: then only the routes andentries()say which pages are rendered. --staticprerenders every page.- The build calls
wisp::prerenderon the app. You never call it yourself.
Service
wisp build, then wisp service install (as root or administrator). It copies the release binary to /usr/local/lib/<name>/ (%ProgramFiles%\<name>\ on Windows) and runs it in the app folder as a boot-time OS service. After a new wisp build, run install again. The other commands are start, stop, status and uninstall (which removes the copy).
wisp host builds the app as you, installs the service with sudo and keeps a list of the apps on the machine (Wisp Host).
| Option | What it does |
|---|---|
--user <name> | run as that user (Windows: a limited task) |
--root | run as root (SYSTEM on Windows); install needs this or --user |
--port <n> | listen port |
--name <service> | service name (default: the package name) |
--dry-run | print what would be written and run, change nothing |
- Linux:
/etc/systemd/system/<name>.servicewithRestart=on-failure,EnvironmentFile=-/etc/<name>.env(made 0600 if missing; putWISP_SECRETthere),LimitNOFILE=1048576, a sandbox (NoNewPrivileges,ProtectSystem=strictwith the app folder as the oneReadWritePaths,PrivateTmp,UMask=0027and more) andAmbientCapabilities=CAP_NET_BIND_SERVICEfor--portbelow 1024. AWISP_DATAelsewhere needs its ownReadWritePathsline viasystemctl edit <name>. The--usermust be able to read the app folder. - macOS:
/Library/LaunchDaemons/wisp.<name>.plist, loaded withlaunchctl. - Windows: a scheduled task at startup (
schtasks).stopends the process without draining.
SIGTERM and Ctrl+C make the runtime stop accepting and drain for up to WISP_DRAIN seconds (10). Server-sent events end cleanly at once; any other streamed body (Response::stream, ndjson) goes on in the drain window, and one the exit still cuts off ends without its last chunk, so the client sees it incomplete rather than a short 200. WISP_STOP_DELAY=5 first serves on for 5 s with /_wisp/health answering 503, so a load balancer moves traffic first. On Linux a systemd .socket unit can pass the listening socket (LISTEN_FDS).
Docker
wisp deploy init docker # --force replaces existing files
docker build -t my-app .
docker run -p 3000:3000 -e WISP_SECRET=... my-app
- It writes a
Dockerfileand.dockerignore. The image builds on a pinnedrust:1.98-slim-trixie(cargo-chef layer) and runs on distrolessgcr.io/distroless/cc-debian13as user 65532 (WISP_USER: the server gives/datato it and drops root itself). It setsHOST=0.0.0.0andWISP_DATA=/data, has aHEALTHCHECKofserver --health, and noVOLUMEline (Railway refuses one). - Its build makes the server only; for a Lambda container image build with
WISP_LAMBDA=1, or usewisp build --target lambda..dockerignorekeeps.envand.env.*out. - Saved tables live in
/data; mount a volume (-v my-app-data:/data). - Docker's default seccomp refuses io_uring, so the server uses an epoll per worker; a profile allowing
io_uring_setup,io_uring_enterandio_uring_registerbrings it back. The first stderr line says which the server uses. Each io_uring worker lends 28 receive buffers, and a quarter more (at least 16) when a receive finds none.
Reproducible builds
Two builds of one commit must give the same binary. These are the parts Wisp gives you:
- Lock file. Commit
Cargo.lock.wisp newdoes not ignore it. The Dockerfile builds with--locked, so a stale lock fails the build.wisp deploy init docker(and the hosts that write a Dockerfile) stops whenCargo.lockis missing. Runcargo generate-lockfileand commit the file. An app inside a Cargo workspace has its lock at the workspace root, and the Dockerfile copies only the app folder, so such an app must build outside the workspace. Usecargo build --release --lockedfor your own builds. The CI file ofwisp deploy initinstalls thewispCLI with--locked, at the release tag thatCargo.tomlof the app pins (--tag v1.0.0-pre.3). It reads the tag of a Wisp dependency written on one line withpackage = "wisp-web(with spaces) andtag = "x"(with spaces). Else it uses the tag of the CLI that wrote the file. This holds for a multi-line[dependencies.wisp]table, fortag="x"with no spaces, for a dependency with nopackagekey, and for a tag that is not a release version.wisp upgradesets the--tagof that file to the new release. - Compiler.
wisp newwritesrust-toolchain.tomlwith the Rust version of the Docker image (channel = "1.98",rustfmtandclippy). Rustup installs that version for the app, so local builds and the image use one compiler. Change the file and theFROMline of theDockerfiletogether. Wisp needs Rust 1.89 or newer. - Targets. A rustup target belongs to one toolchain. For an edge build (
--target cloudflare,denoand the others) runrustup target add wasm32-unknown-unknownin the app folder, so rustup adds it to the pinned toolchain. The build error names this command. - Paths.
App::ROOTis"."in a release build. A release build with the build cache (wisp build) remaps the cache folder to./targetand the workspace folder to a relative path. Any other release build remaps a path in the folder of the workspace to a relative path (also in compiler errors). YourRUSTFLAGSand cargo config apply as before. The binary then has no path of the app folder. Paths of path dependencies and of$CARGO_HOMEand the Rust toolchain stay in it. This holds for an app with only a binary target and no[[bin]]orautobins. Other apps build plain: the path stays in the binary (with a library target: in the library, and with the cache it is the cache folder). The Docker image always builds in/app. - Image tools. The Dockerfile pins the Rust image and the
cargo-chefversion. - Time. Wisp writes no clock time in the bytes of the generated code or the static export. It does not read
SOURCE_DATE_EPOCH, because it has no timestamp to set. A test generates the code twice and exports the test app twice, and checks that the bytes are the same.
An export (wisp build --static) empties the nonce="…" value of a tag and the token of the <form guard> input in the pages it writes. A static page has no visitor to bind them to, and a random value would change every file on each build. A guarded action refuses an empty token, so a guarded form needs a running Wisp server. If your app uses wisp::csp_nonce(), its exported pages have no nonce. The exported _headers use the hash policy, so an inline script that needs a nonce can fail there. Test the exported site with wisp preview --static.
Is This Page Useful?