Add BTCPay Server overlay for local Bitkit testing

[jvsena42]

Context

Bitkit Android is adding BTCPay wallet-connection support (bitkit-android#961) — the user scans a SamRock setup link from a BTCPay store and Bitkit registers an on-chain receive descriptor with that store. Testing this flow locally requires an NBXplorer + BTCPay Server pair pointed at the same regtest chain Bitkit already uses.

bitkit-docker doesn't have anything BTCPay-related today. While bringing PR #961 up locally I ended up writing a small overlay compose file that reuses this repo's existing bitcoind and postgres. It would be useful to land that here so anyone testing BTCPay against Bitkit (or working on follow-up features like Boltz, payouts, etc.) gets a working stack with one command.

Proposed addition

A new docker-compose.btcpay.yml overlay that adds two services and reuses what's already here:

services:
  nbxplorer:
    image: nicolasdorier/nbxplorer:2.6.7
    container_name: nbxplorer
    restart: unless-stopped
    depends_on: [bitcoind, postgres]
    ports: ["32838:32838"]
    environment:
      NBXPLORER_NETWORK: regtest
      NBXPLORER_CHAINS: "btc"
      NBXPLORER_BTCRPCURL: http://bitcoind:43782
      NBXPLORER_BTCRPCUSER: polaruser
      NBXPLORER_BTCRPCPASSWORD: polarpass
      NBXPLORER_BTCNODEENDPOINT: bitcoind:39388
      NBXPLORER_BIND: 0.0.0.0:32838
      NBXPLORER_NOAUTH: "true"
      NBXPLORER_POSTGRES: "Host=postgres;Port=5432;Database=nbxplorer;Username=postgres;Password=postgres"

  btcpayserver:
    image: btcpayserver/btcpayserver:2.3.9
    container_name: btcpayserver
    restart: unless-stopped
    depends_on: [nbxplorer, postgres]
    ports: ["14142:14142"]
    environment:
      BTCPAY_NETWORK: regtest
      BTCPAY_BIND: 0.0.0.0:14142
      BTCPAY_ROOTPATH: /
      BTCPAY_PROTOCOL: http
      BTCPAY_CHAINS: "btc"
      BTCPAY_BTCEXPLORERURL: http://nbxplorer:32838/
      BTCPAY_POSTGRES: "Host=postgres;Port=5432;Database=btcpay;Username=postgres;Password=postgres"
      BTCPAY_EXPLORERPOSTGRES: "Host=postgres;Port=5432;Database=nbxplorer;Username=postgres;Password=postgres"

Used as: docker compose -f docker-compose.yml -f docker-compose.btcpay.yml up -d.

Gotchas I hit while validating it

1. Postgres needs the BTCPay/NBXplorer databases bootstrapped. The existing sql/v0_create_vss_db.sql only creates the VSS table on the default postgres DB. On a clean down -v + up, both BTCPay and NBXplorer crash with:

   Error while trying to connection to explorer.postgres: 3D000:
   database "nbxplorer" does not exist
   

   Fix: ship a second init script (e.g. sql/v1_create_btcpay_dbs.sql) with CREATE DATABASE nbxplorer; and CREATE DATABASE btcpay; and mount it alongside the VSS one. Postgres runs everything in /docker-entrypoint-initdb.d/ on first boot.

2. No healthcheck on btcpayserver. First boot takes ~60s (Entity Framework migrations); without a healthcheck, scripts that want to wait for BTCPay to be ready have to poll :14142 themselves.

3. Android emulator port plumbing isn't obvious. Bitkit's setup-link parser only accepts loopback / RFC1918 hosts for HTTP. From an emulator that means either using 10.0.2.2:14142 directly, or:

   adb reverse tcp:60001 tcp:60001   # electrs
   adb reverse tcp:14142 tcp:14142   # btcpay

   Worth a short README section alongside the existing testing guides.

Suggested follow-ups

In priority order, smallest to biggest:

• Add the overlay file.
• Add the Postgres init script for nbxplorer and btcpay.
• Add a healthcheck for btcpayserver (HTTP GET on /).
• Add a BTCPay section to README.md with the bring-up command and the emulator port-forwarding notes.
• Optional helper script (e.g. scripts/setup-btcpay-store.sh) that, once BTCPay is healthy, registers an admin user via the API, creates a regtest store, enables on-chain BTC, and prints a SamRock setup URL ready to paste/deeplink into Bitkit — turning the 10-step manual setup into one command.

Happy to send a PR for items 1-4 if useful; the helper script is the bigger piece and may want a separate issue.

[ovitrif]

Cool proposal, lmk if you need me to work on it or you're happy to own this one.
I would do only one adjustment, instead of reusing postgres, I would add another postgres-btcpay service and in a separate PR would rename the current one to postgres-vss so they're all split-able and can be independent if needed.