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

Wisp

Host on a VPS

A VPS is a server you rent and run yourself. On it, Wisp runs as one binary with no runtime to install. WebSockets, streaming and saved tables on disk work.

On the server, run wisp host as your own user. It builds the app as you, then runs sudo and installs the service of this page. As root it does not build, so run wisp build first (Wisp Host). This page shows the steps by hand.

Build

wisp build

This makes one release binary with the static files and styles inside. A native binary runs only on the OS and CPU it was built for, so build on the server or on a machine like it.

Deploy

Copy Cargo.toml and the binary to the app folder on the server, and run it. It listens on $HOST:$PORT (0.0.0.0:3000 in release).

ssh me@server 'mkdir -p /srv/my-app/target/release'
scp Cargo.toml me@server:/srv/my-app/
scp target/release/my-app me@server:/srv/my-app/target/release/
ssh me@server 'cd /srv/my-app && WISP_SECRET=... ./target/release/my-app'

wisp service install reads the package name in Cargo.toml and the build in target/release of the app folder. So the server needs both files, and wisp must be installed there. The account my-app of --user my-app must exist. To keep the app running and start it at boot, run this on the server from the app folder, as root:

wisp service install --user my-app --port 3000
wisp service status

On Linux this writes a systemd unit with Restart=on-failure and EnvironmentFile=-/etc/<name>.env. The unit is sandboxed: NoNewPrivileges, ProtectSystem=strict with the app folder as its one ReadWritePaths, ProtectHome=read-only, PrivateTmp, PrivateDevices and the kernel protections. A WISP_DATA outside the app folder is read-only under ProtectSystem=strict, so saved tables fail to write there: add it with systemctl edit <name>, a [Service] section with ReadWritePaths=/var/lib/my-app, then systemctl restart <name>. See Deploying for every option, and for macOS and Windows.

Environment

  • WISP_SECRET: 32 or more random characters, needed by an app that signs cookies. With wisp service install on Linux, put it in /etc/<name>.env (made 0600 if missing).
  • HOST, PORT, WISP_THREADS and the rest: Environment variables.

Limits

  • There is no TLS in the server. Put a reverse proxy in front for HTTPS, and set WISP_CLIENT_IP_HEADER=x-real-ip so cx.client_ip() sees the real address (the nginx and Caddy setups in Deploying set X-Real-IP).
  • SIGTERM and Ctrl+C stop accepting and drain for up to WISP_DRAIN seconds (10). Before that, the server serves on for WISP_STOP_DELAY seconds with /_wisp/health at 503.
  • systemd socket activation works: a .socket unit (ListenStream=3000, ReusePort=yes) hands the server its socket through LISTEN_FDS. Not checked: that a restart refuses no connection.
  • WebSockets and streaming both work.

Files and Data

  • static/ and the styles are inside the binary.
  • Saved tables (Table::saved, #[derive(Rest)]) are log files in the data folder next to where you run it. WISP_DATA moves it. Back that folder up. See Where rows are kept.
  • wisp::kv and wisp::blobs are files under .wisp/data ($WISP_DATA/storage when WISP_DATA is set). Back it up with the tables. See Storage.

More

Deploying, Logs, metrics and traces, Serve extras.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.