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

Wisp

Host on Cloud Run

Cloud Run runs a container image. Wisp builds the Dockerfile as it is.

Build

wisp deploy init cloud-run   # service.yaml, 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.

service.yaml is a Cloud Run service. The Dockerfile is the one wisp deploy init docker writes. --force replaces the file. What the service sets:

  • Container port 3000, which Cloud Run passes as PORT.
  • A startup probe and a liveness probe on /_wisp/health, which answers 503 once the server is stopping.
  • autoscaling.knative.dev/maxScale: "1", for saved tables (below).
  • timeoutSeconds: 3600: WebSockets and event streams are requests, and end at the request timeout (60 minutes at most).
  • WISP_SECRET from the Secret Manager secret wisp-secret.

Deploy

openssl rand -hex 32 | gcloud secrets create wisp-secret --data-file=-
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT/REPOSITORY/my-app
gcloud run services replace service.yaml

Put your image in place of the one in service.yaml first. The service account needs roles/secretmanager.secretAccessor on the secret. gcloud run deploy --source . also builds the Dockerfile, without the file's probes and limits.

Environment

  • WISP_SECRET: 32 or more random characters, for an app that signs cookies (the secret above).
  • The client's address: Google's front end lists the visitor and then a load balancer in X-Forwarded-For, so service.yaml sets WISP_CLIENT_IP_HEADER=x-forwarded-for and WISP_CLIENT_IP_DEPTH=2: cx.client_ip() is the entry before the load balancer's.
  • Other variables: Environment variables.

Shutdown

Cloud Run sends SIGTERM and kills the instance 10 s later, and that window cannot be changed. The server drains for up to WISP_DRAIN (10 s), so set it lower (WISP_DRAIN=8) to finish inside the window; a request still running near its end is cut. Keep requests short of that, or let the client retry.

HTTP/2

Requests over 32 MB and streams in both directions need HTTP/2 end to end. Build with the h2 feature (wisp = { version = "..", features = ["h2"] }), which answers HTTP/2 without TLS (h2c) and HTTP/1 on the same port. Then name the port h2c in service.yaml (- name: h2c above containerPort: 3000), or deploy with --use-http2. The probes stay HTTP/1, as Cloud Run requires.

Wisp's h2c takes WebSockets over HTTP/2 (RFC 8441), but Cloud Run's WebSocket guide says not to turn on HTTP/2 end to end: an app with WebSockets or live pages keeps the default (HTTP/1 to the container).

Limits

  • The image is the Docker one: epoll instead of io_uring under Docker's default profile.
  • WebSockets and streaming work over HTTP/1 (above).

Files and Data

  • static/ and the styles are inside the binary.
  • Saved tables live in /data, which on Cloud Run is the instance's memory: rows go when the instance stops, and two instances keep two sets. maxScale: "1" keeps one set. To keep rows across restarts, give the tables a shared store (Where rows are kept).
  • wisp::kv and wisp::blobs default to files under $WISP_DATA/storage, which go with the instance: set upstash or s3: for lasting data. See Storage.

More

Host with Docker, Deploying.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.