Hypothesis (self-hosted)

Hypothesis is an open-source web annotation tool. h is the server that powers it: it serves the annotation web app and the public annotation API. With a self-hosted instance you and your collaborators can highlight, annotate, and discuss any web page or PDF on infrastructure you control.

This template deploys four services as a single one-click stack:

• hypothesis — the h server (web app, API, real-time WebSocket, background worker)
• postgresql — stores accounts, groups, and annotations
• elasticsearch — powers annotation search (uses Hypothesis's ICU-enabled build)
• rabbitmq — message broker for the background worker

Getting started

1. Enter the domain you want to use and click Deploy.
2. Wait for all four services to finish deploying. The hypothesis service runs a one-time initialization on first boot (database schema, search index, and admin account), so its first start takes a few minutes — this is normal.
3. Open your domain. You should see the Hypothesis homepage.

Logging in

An administrator account is created automatically on first boot:

• Username: admin
• Password: see the ADMIN_PASSWORD variable on the hypothesis service (Variables tab in the Zeabur dashboard)

Sign in at https://YOUR_DOMAIN/login, then change this password immediately from the account settings page. Admin tools are available at https://YOUR_DOMAIN/admin.

Using a custom domain

The annotation "authority" and public URL are derived from the domain at deploy time. If you want to use a custom domain, bind it before your first deployment, or be prepared to redeploy: changing the domain after accounts and annotations exist will leave them tied to the old authority.

Important notes

• The annotation client is loaded from https://cdn.hypothes.is. This is Hypothesis's default and keeps the client up to date; your annotation data stays entirely on your own instance.
• Email is not configured. Account activation is skipped, and password-reset emails will not be sent unless you add MAIL_* environment variables to the hypothesis service.
• Data lives in the postgresql and elasticsearch volumes. The hypothesis service itself is stateless. Do not delete those volumes.
• The PostgreSQL, Elasticsearch, and RabbitMQ services are reachable only inside the project's private network — Elasticsearch in particular has no authentication, so do not expose it publicly.

Attribution & license

Hypothesis (h) is developed by the Hypothes.is Project and contributors and is released under the BSD-2-Clause license. This template only packages the official hypothesis/hypothesis Docker image for deployment on Zeabur; it is not affiliated with or endorsed by the Hypothes.is Project.

• Source code: https://github.com/hypothesis/h
• Official website: https://web.hypothes.is/

Changelog

• 2026-05-14: Initial release. Based on hypothesis/hypothesis:20260504-g4d0056f.