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

Wisp

Host on Railway

Railway builds a Dockerfile from your repository and runs it as a service.

Build

wisp deploy init railway      # .railway/railway.ts, 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 .railway/railway.ts, Railway's infrastructure as code. Railway's infrastructure-as-code page says new services cannot use railway.toml or railway.json, and existing ones stop reading them on 2026-12-01. The file declares:

  • One service built from your GitHub repository, read from the origin remote (else OWNER/REPO, to fill in). Railway builds the Dockerfile at its root.
  • healthcheck: "/_wisp/health". A new deploy takes traffic only once it answers 200, and the path answers 503 once the server is stopping.
  • RAILWAY_DEPLOYMENT_DRAINING_SECONDS: "15". By default Railway kills the old deploy as soon as it sends SIGTERM, while the server drains for up to 10 s.
  • WISP_CLIENT_IP_HEADER: "x-real-ip". Railway's edge sets X-Real-IP to the visitor's address and replaces one the visitor sent.
  • A 1 GB volume mounted at /data, where saved tables live, and replicas: 1. A volume belongs to one replica. The Dockerfile's entrypoint makes it writable by nobody, so RAILWAY_RUN_UID needs no change.

The Dockerfile is the one wisp deploy init docker writes. It has no VOLUME line, which Railway's builder refuses. --force replaces the file.

Deploy

npm install railway
railway link
railway config apply

railway config plan shows the changes first. Railway builds the Dockerfile on each push and sets PORT, which the app listens on.

Environment

  • WISP_SECRET: 32 or more random characters, in the service's variables, for an app that signs cookies.
  • Other variables: Environment variables.

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 on the volume at /data, on the one replica. For more replicas, give the tables a shared store first (Where rows are kept).
  • wisp::kv and wisp::blobs default to files under $WISP_DATA/storage, beside the tables. See Storage.

More

Host with Docker, Deploying.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.