Configuring the URLs
The three addresses
Bancwr uses three addresses. Each one is set in a different place:
| Address | Who uses it | Set by |
|---|---|---|
The console's public address, such as https://bancwr.example | People signing in, and apps waiting for an approval | NUXT_SITE_ORIGIN in .env |
The bunker's internal address, http://bunker:3000 | The console, and nothing else | NUXT_API_BASE in compose.yaml |
The bunker:// connection string | Nostr apps connecting over NIP-46 | The bunker's key and its relays |
The console's public address
NUXT_SITE_ORIGIN is the HTTPS address people open Bancwr on, such as https://bancwr.example.
- Give the scheme and the host, and a port if it is not the default. No path, and no trailing slash.
- It must be exactly the address in the browser's address bar.
- Compose refuses to start without it.
Compose also passes it to the bunker as BANCWR_CONSOLE_URL. When an app asks for a signature that needs an administrator's approval, the bunker points the app at that address, at /approvals/<id>. See Approval before signing.
Why sign-in needs HTTPS
The console's sign-in cookie is Secure, so browsers only send it over HTTPS, or to http://localhost.
- The console refuses to start if
NUXT_SITE_ORIGINis plainhttp://for any other host. Its log says:NUXT_SITE_ORIGIN must be https:// (http:// is allowed only for localhost). - For testing on one machine,
NUXT_SITE_ORIGIN=http://localhost:3001works without TLS.
"This page's address does not match"
Each sign-in event names the console's address, and the console refuses one that names another address. If you open Bancwr at any address other than NUXT_SITE_ORIGIN, the sign-in page says:
This page's address does not match the address Bancwr is configured with (NUXT_SITE_ORIGIN).
To fix it, open Bancwr at exactly the address in NUXT_SITE_ORIGIN. Look for:
httpagainsthttps,www.on one and not the other,- a port, such as
:3001, on one and not the other, - a trailing slash or a path in
NUXT_SITE_ORIGIN.
If you change the address people use, change NUXT_SITE_ORIGIN to match and recreate both containers with podman compose up -d.
How the console reaches the bunker
The console talks to the bunker over the compose network, at http://bunker:3000. compose.yaml sets this as NUXT_API_BASE on the console. You do not need to change it.
- The bunker's port is never published on the host. Only the console reaches it.
- Only the console goes behind your reverse proxy. Never expose the bunker's API directly.
- The bunker answers only requests the console has signed with
BANCWR_PROXY_SECRET, naming the signed-in key. It checks that key's role on every request. The bunker does not start without the secret.
If you run the console image outside compose, set NUXT_API_BASE to the bunker's address yourself. Its default, http://localhost:3000, is the console's own port inside its container, so it will not reach the bunker.
To change BANCWR_PROXY_SECRET, set a new value in .env and recreate both containers. Compose passes the one value to both.
The connection string apps use
Apps connect to the bunker with a bunker:// connection string, which an administrator issues as a connection token under Connections. NIP-46 defines its form:
bunker://<bunker public key in hex>?relay=wss://relay.one&relay=wss://relay.two&secret=<token secret>
It is built from:
- the public key of the identity the token signs as: the bunker's own key, or another identity it holds (see Signing identities),
- every relay in the bunker's relay list, one
relay=for each, - the token's secret, shown once.
There is no URL for the bunker on the internet. Apps and the bunker meet on the relays.
Choosing the bunker's relays
After you first sign in, choose the relays under Config, Bunker relays:
- Search the known relays, from reports that relay monitors publish (NIP-66), or enter an address under Add a relay and click Add.
- Choose 1 to 6 relays. 2 or more is advised, so one relay going down does not cut apps off.
- Addresses must be
wss://. Plainws://is accepted only forlocalhost. - Click Save relays. The bunker uses the new list straight away, without a restart.
The list is kept in the bunker's database. It is never published to Nostr, and it is not the same as any member's own relay list.
Until there is at least 1 relay, the Relays health check is red and no token can be issued.
Fixing the relays with NIP46_RELAYS
To set the relays in .env instead, set NIP46_RELAYS to a comma-separated list:
NIP46_RELAYS=wss://relay.nsec.app,wss://relay.damus.io
Then recreate the bunker with podman compose up -d.
- While it is set, it always decides. Bunker relays shows the list read-only, with each relay's status.
- A list saved in the console is ignored, and kept. To manage the relays in the console again, unset
NIP46_RELAYSand recreate the bunker.
When the relays change
An app learns the bunker's relays from its bunker:// string, and keeps using them.
- Adding a relay does not affect connected apps. New connection strings carry it.
- Removing a relay an app uses cuts that app off. Before you save a removal, the console warns you and the button reads Save and remove. The app must connect again with a new connection token, whose string carries the current list.
The reverse proxy
Put a TLS reverse proxy in front of the console, at 127.0.0.1:3001, for the host in NUXT_SITE_ORIGIN.
With Caddy, which obtains and renews certificates itself:
bancwr.example {
reverse_proxy 127.0.0.1:3001
}
On a local network with no public name
Caddy cannot get a public certificate for a name only your network knows. Add tls internal to the block, and Caddy uses its own certificate authority:
bancwr.lan {
tls internal
reverse_proxy 127.0.0.1:3001
}
Each browser that opens Bancwr then has to trust Caddy's root certificate. Set NUXT_SITE_ORIGIN to the same name, such as https://bancwr.lan.