Configuring the URLs

The three addresses

Bancwr uses three addresses. Each one is set in a different place:

AddressWho uses itSet by
The console's public address, such as https://bancwr.examplePeople signing in, and apps waiting for an approvalNUXT_SITE_ORIGIN in .env
The bunker's internal address, http://bunker:3000The console, and nothing elseNUXT_API_BASE in compose.yaml
The bunker:// connection stringNostr apps connecting over NIP-46The 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_ORIGIN is plain http:// 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:3001 works 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:

  • http against https,
  • 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://. Plain ws:// is accepted only for localhost.
  • 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_RELAYS and 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.