Environment Variables

LaWallet ships a generator so operators do not need to invent, copy, or accidentally reuse deployment secrets. It creates independent 256-bit values, sets private file permissions, and refuses to overwrite existing output.

Fastest complete Docker deployment

Download the published Compose file and generator:

curl -fsSLO https://raw.githubusercontent.com/lawalletio/lawallet-nwc/main/docker-compose.hub.yml
curl -fsSLO https://raw.githubusercontent.com/lawalletio/lawallet-nwc/main/scripts/generate-deployment-env.sh
chmod +x generate-deployment-env.sh

Generate .env and start web, listener, and Postgres:

./generate-deployment-env.sh --mode compose --output .env
docker compose -f docker-compose.hub.yml up -d

The generated .env enables the private listener automatically through COMPOSE_PROFILES=listener. It is written with mode 600 and the generator will not replace it on a later run.

From a cloned repository, the equivalent shortcut is:

pnpm deploy:env
docker compose up -d

Vercel or Netlify with a separate listener

Serverless platforms run the web app but cannot keep the listener's Nostr WebSocket subscriptions alive. Generate a matched pair of files:

pnpm deploy:env:cloud

Or run the downloaded script directly:

curl -fsSLO https://raw.githubusercontent.com/lawalletio/lawallet-nwc/main/scripts/generate-deployment-env.sh
chmod +x generate-deployment-env.sh
./generate-deployment-env.sh \
  --mode cloud \
  --output lawallet-cloud-env

This creates:

• lawallet-cloud-env/web.env — enter these values in Vercel or Netlify.
• lawallet-cloud-env/listener.env — enter these values on the always-on listener host.

Replace the DATABASE_URL, LISTENER_URL, and WEB_ORIGIN placeholders before deploying. Both services must use the same database, NWC vault key, and listener authentication values.

What the generator creates

Every generated secret is independent. Do not use JWT_SECRET, KEY_VAULT_SECRET, or either listener secret as NWC_VAULT_SECRET.

Connection and runtime variables

The complete list of lower-level tuning variables is documented in apps/web/.env.example and the listener setup guide.

Error monitoring (optional)

Sentry integration is entirely optional and off by default. Self-hosters who do not use Sentry leave all three variables unset — nothing is collected and no Sentry code is activated.

Vault secrets are not rotatable

KEY_VAULT_SECRET and NWC_VAULT_SECRET each have exactly one value, and it is the only key that opens what it sealed. There is no previous-secret fallback: changing either one makes the existing ciphertext unreadable.

Back both up and keep them stable. Recovery from a changed secret is per credential, not automatic:

Do not change or remove proxy credentials while non-completed proxy payments exist.

Values configured in Admin Settings

These values are intentionally not generated as environment variables:

User and LNCurl RemoteWallet NWC connection strings, the proxy NWC URI, and the receipt signer nsec all use the same lwrw1: envelope under NWC_VAULT_SECRET. A startup pass encrypts leftover plaintext RemoteWallet rows and converts leftover LWPX01 proxy blobs, then reports anything the active secret cannot open. Startup still refuses to begin when NWC RemoteWallets exist and the key is missing entirely, but a single credential sealed under a retired secret is a per-credential fault, not an outage: that wallet returns 503 on its own payment paths and the rest of the instance serves normally. The listener must use the same key so it can open the connections.

The NIP-57 receipt signer is the exception, because one unusable signer turns zaps off for every NWC wallet. Startup guarantees a usable one: it generates a signer when the config row has none, derives a missing pubkey from a readable key, and — when NWC_VAULT_SECRET cannot open the stored key — replaces it and updates the advertised pubkey in the same statement, so zaps recover with no operator action.

A replacement changes the instance's _ identity, and the displaced key is gone (it was already unopenable). To keep the original identity across a secret change, re-enter that nsec in Admin → Settings → NWC Services before the instance restarts. proxy_receipt_signer.replaced_unreadable logs both the old and new pubkey.

The listener receives the NWC vault key because it must decrypt RemoteWallet and proxy NWC connections. It never receives the NIP-57 nsec.

Platform summary

Never commit generated files, paste them into support tickets, or expose them through generic Settings/backup APIs.