Public address
An ingress plugin gives the library an address on the internet without port forwarding, a reverse proxy or a certificate of your own. Branches and clerks away from home reach the library there.
There are two kinds of ingress plugin:
- A relay keeps an outbound connection to a provider (such as a relay Worker in your own Cloudflare account). Requests arrive over that connection and the plugin hands them to the library. TLS ends at the provider's edge.
- A direct plugin keeps a DNS name pointing at this computer.
Traffic comes to the built-in TLS listener (
acmemode), so TLS ends at home.
The design is in the ingress plugins ADR. Plugin authors start at Public addresses.
- Claim the library first. Ingress stays off until an Owner account exists, so first-run setup is never public.
- Keep operator auth on. Ingress stays off while
daemon.auth.enabled = false, because public traffic would reach the library without signing in. - Run the daemon as a server. Only
bookclerkdserves a public address; the desktop window does not.
-
Install and approve the ingress plugin, then deploy it on the computer that runs the library (see Managing plugins).
-
Make it the library's active ingress:
bookclerk ingress activate <plugin><plugin>is a plugin key (its default instance) or a plugin instance UUID. A library has at most one active ingress. -
Check that it is serving:
bookclerk ingress statusserving asshows the public origin once the plugin reports it.
The plugin starts within a few seconds. The first origin it reports is
adopted as the library's public origin and stored in the library
database, so it survives restarts and needs no config.toml change.
Turn it off with bookclerk ingress deactivate. The adopted origin is
kept, so turning the same provider back on serves under the same name.
The same settings are on the web API as GET and POST /api/config/ingress (the operator, or an elevated Owner).
Choose what public traffic may reach:
bookclerk ingress exposure branches # the default
bookclerk ingress exposure library
| Exposure | Serves |
|---|---|
branches (default) |
The node API, the clerk and copy routes, sign-in (password, passkey, authenticator app and OIDC), the branch and clerk consent screens, and the web app's pages. Nothing else under /api/, and none of the legacy control routes (/status, /scan, /acquire, /jobs, /integrations). |
library |
The whole library, web app included. |
Some things never pass, whatever the exposure:
- the operator token, as a bearer token or through operator sign-in
(
/api/auth/login), and the operator session cookie; - the tray handoff, operator elevation and first-Owner setup.
A refused request gets 403 with "error": "operator_only" or
"error": "not_exposed".
Note
Every request through a relay is treated as public https traffic,
never as loopback. Its client address is the one the plugin reports
from the provider's own connection metadata; forwarding headers in the
request are dropped.
integrations.public_origin in config.toml still wins when it is set.
Leave it unset to use the ingress origin.
If the active plugin later reports a different name, the library keeps
serving under the old one and bookclerk ingress status shows the new
one as reported origin. Accept it with:
bookclerk ingress accept-origin
Warning
Renaming the library breaks passkeys registered under the old name and sign-in redirects that name it. Patrons sign in another way and add their passkeys again.
Set [daemon.node_api] mode = "tunnel" so the node API accepts requests
the relay carries (see
Configuration → Node API transport).
Branches verify the relay's edge certificate against the public roots,
as in acme and proxy mode; it can't be pinned.
Invite links name the public origin, from the daemon and from
bookclerk nodes invite alike.
- No first-party ingress plugin ships yet. The Cloudflare relay comes next, then ngrok, Cloudflare Tunnel and dynamic DNS.
ORIGINcarries plain HTTP requests, not WebSocket upgrades. A branch's live socket and a clerk's live link need one, so over a relay they don't connect yet; enrollment, sign-in, uploads and copies work.- There is no web app screen yet; use the CLI or the web API.
- Libraries and branches: join a library and let branches in.
- Security checklist: before you expose a server.
Source: docs/server/ingress.md at main · View as Markdown