BTCPay Server development environment cheatsheet

BTCPayServer development environment cheat sheet

Environment variables

btcpay-setup.sh will use the following environment variables:

BTCPAY_HOST: The hostname of your website (eg. btcpay.example.com)
BTCPAY_ADDITIONAL_HOSTS: Optional, specify additional domains to your BTCPayServer with https support if enabled. (eg. example2.com,example3.com)
REVERSEPROXY_HTTP_PORT: The public port the reverse proxy binds to for HTTP traffic (default: 80)
REVERSEPROXY_HTTPS_PORT: The public port the reverse proxy binds to for HTTPS traffic (default: 443)
REVERSEPROXY_DEFAULT_HOST: Optional, if using a reverse proxy nginx, specify which website should be presented if the server is accessed by its IP.
NBITCOIN_NETWORK: The type of network to use (eg. mainnet, testnet, or regtest. Default: mainnet)
LIGHTNING_ALIAS: An alias for your lightning network node, if used
BTCPAYGEN_CRYPTO1: First supported crypto currency (eg. btc, ltc. Default: btc)
BTCPAYGEN_CRYPTO2: Second supported crypto currency (eg. btc, ltc. Default: (empty))
BTCPAYGEN_CRYPTON: N'th supported crypto currency where N is 9 at maximum. (eg. btc, ltc. Default: (empty))
BTCPAYGEN_REVERSEPROXY: Specify reverse proxy to use; NGinx has HTTPS support. (eg. nginx, traefik, (empty). Default: nginx)
BTCPAYGEN_LIGHTNING: Lightning network implementation to use (eg. clightning, lnd, Default: (empty))
BTCPAYGEN_SUBNAME: The subname of the generated docker-compose file, where the full name is Generated/docker-compose.SUBNAME.yml (Default: generated)
BTCPAYGEN_ADDITIONAL_FRAGMENTS: Semicolon-separated list of additional fragments you want to use (eg. opt-save-storage)
LETSENCRYPT_EMAIL: An email will be sent to this address if certificate expires and fails to renew automatically (eg. me@example.com)
ACME_CA_URI: The API endpoint to ask for HTTPS certificate (Default: production)
BTCPAY_ENABLE_SSH: Optional, gives BTCPay Server SSH access to the host by allowing it to edit authorized_keys of the host, it can be used for managing the authorized_keys or updating BTCPay Server directly through the website. (Default: false)
BTCPAYGEN_DOCKER_IMAGE: Optional, Specify which generator image to use if you have customized the C# generator. Set to btcpayserver/docker-compose-generator:local to build the generator locally at runtime.
BTCPAY_IMAGE: Optional, Specify which btcpayserver image to use if you have a customized btcpayserver.
BTCPAYGEN_EXCLUDE_FRAGMENTS: Semicolon-separated list of fragments you want to forcefully exclude (eg. litecoin-clightning)
TOR_RELAY_NICKNAME: If tor relay is activated with opt-add-tor-relay, the relay nickname
TOR_RELAY_EMAIL: If tor relay is activated with opt-add-tor-relay, the email for Tor to contact you regarding your relay
Additionally, there are specific environment variables for some addons:

LIBREPATRON_HOST: If libre patron is activated with opt-add-librepatron, the hostname of your libre patron website (eg. librepatron.example.com)
WOOCOMMERCE_HOST: If woocommerce is activated with opt-add-woocommerce, the hostname of your woocommerce website (eg. store.example.com)
BTCTRANSMUTER_HOST: If btctransmuter is activated with opt-add-btctransmuter, the hostname of your btctransmuter website (eg. transmuter.example.com)
Tooling

A wide variety of useful scripts are available once BTCPay is installed:

bitcoin-cli.sh: Access your Bitcoin node instance (for RPC)
bitcoin-lightning-cli.sh: Access your C-Lightning node instance (for RPC)
changedomain.sh: Change the domain of your BTCPayServer
btcpay-update.sh: Update BTCPayServer to the latest version
btcpay-up.sh: Run docker-compose up
btcpay-down.sh: Run docker-compose down
btcpay-setup.sh: Change the settings of your server
. ./btcpay-setup.sh: Information about additional parameters
. ./btcpay-setup.sh -i: Set up your BTCPayServer
Under the hood

Generated docker-compose

When you run btcpay-setup.sh, your environment variables are used by build.sh (or build.ps1) to generate a docker-compose adapted for your needs. For the full list of options, see: Environment variables

By default, the generated file is Generated/docker-compose.generated.yml, constructed from the relevant Docker fragments for your setup.

Available BTCPAYGEN_ADDITIONAL_FRAGMENTS currently are:

opt-save-storage will keep around 1 year of blocks (prune BTC for 100 GB)
opt-save-storage-s will keep around 6 months of blocks (prune BTC for 50 GB)
opt-save-storage-xs will keep around 3 months of blocks (prune BTC for 25 GB)
opt-save-storage-xxs will keep around 2 weeks of blocks (prune BTC for 5 GB) (lightning not supported)
opt-lnd-autopilot will activate auto pilot on LND. (5 channels, 60% of allocation)
opt-save-memory will decrease the default dbcache at the expense of longer synchronization time. (Useful if your machine is less than 2GB)
opt-more-memory will increase the default dbcache to make synchronization faster (Useful if your machine is has around 4GB)
opt-add-btcqbo will allow you to create an invoice on Quickbooks which include a way for your customer to pay on BTCPay Server (More information on this github repository, this add-on is maintained by JeffVandrewJr, see more on this video)
opt-add-librepatron, for a self-hosted Patreon alternative backed by BTCPay (More information on this github repository, this add-on is maintained by JeffVandrewJr.
opt-add-woocommerce, for a self-hosted woocommerce with BTCPay Server plugin pre installed.
opt-add-tor, for exposing BTCPayServer, Woocommerce, your lightning nodes as hidden services and accept onion peers for your full node. Warning: This options is for working around NAT and firewall problems as well as to help protect your customer's privacy. This will not protect your privacy against a targeted attack against you.
opt-add-btctransmuter, for a self-hosted IFTTT style service for crypto services such as fiat settlement.
opt-txindex, to enable txindex=1 in bitcoin.conf if you require txindexing for Bisq, DOJO, Esplora, etc.
opt-unsafe-expose, to unsafely expose bitcoind P2P port 8333 if you require P2P for Bisq, DOJO, Esplora, etc. WARNING: ONLY USE ON TRUSTED LAN OR WITH FIREWALL RULES WHITELISTING SPECIFIC HOSTS
opt-add-tor-relay, for a non-exit tor relay. Make sure to have ports 9001 and 9030 accessible externally. Please read the legal implications of running a tor relay and what resources are used to operate the relay.
opt-add-electrumx, to integrate a full ElectrumX server (from official source) with BTCPay, using the BTCPay server's full bitcoin node for complete privacy when using your own Electrum wallet. You can also open port 50002 up to the internet on your router etc, to be part of the ElectrumX network, helping other Electrum wallet users to get connected. The bitcoin option -txindex is mandatory for ElectrumX, and this fragement will enable it on your BTCPay server automatically - NO need to use the fragment opt-txindex.yml.
You can also create your own custom fragments.

If you want to add an option to BTCPAYGEN_ADDITIONAL_FRAGMENTS and re-configure your install:

export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-lnd-autopilot"
. btcpay-setup.sh -i
For example, if you want btc and ltc support with nginx and clightning inside Generated/docker-compose.custom.yml:

Note: The first run might take a while, but following runs are instantaneous.

On Windows (run in powershell):

Invoke-Command {
    $BTCPAYGEN_CRYPTO1="btc"
    $BTCPAYGEN_CRYPTO2="ltc"
    $BTCPAYGEN_REVERSEPROXY="nginx"
    $BTCPAYGEN_LIGHTNING="clightning"
    $BTCPAYGEN_SUBNAME="custom"
    . .\build.ps1
}
On Linux:

BTCPAYGEN_CRYPTO1="btc" \
BTCPAYGEN_CRYPTO2="ltc" \
BTCPAYGEN_REVERSEPROXY="nginx" \
BTCPAYGEN_LIGHTNING="clightning" \
BTCPAYGEN_SUBNAME="custom" \
./build.sh
Next, you will need to configure the runtime environment variables for Generated/docker-compose.custom.yml:

If you are using NGinx, read this.
If you are not using NGinx, read this instead.