# Customization
The generated Compose file is assembled from fragments. Do not edit
Generated/docker-compose.generated.yml directly; setup and updates overwrite
it.
# Create a Custom Fragment
Custom fragment filenames should end in .custom.yml. That suffix is ignored
by Git, avoiding conflicts during updates.
For example, copy the 100 GB pruning profile:
cp docker-compose-generator/docker-fragments/opt-save-storage.yml \
docker-compose-generator/docker-fragments/opt-save-storage.custom.yml
Edit the custom file, then select its basename:
btcpay-fragments add opt-save-storage.custom
Fragment changes require root and immediately run setup to regenerate and apply the stack. They are not selection-only edits.
The command preserves other selected fragments. Remove the custom fragment with:
btcpay-fragments remove opt-save-storage.custom
# Fragment Metadata
See Declare Relationships for the canonical metadata reference. Use existing fragments as examples and validate the resulting Compose file.
# Use an Existing Bitcoin Core Node
This advanced configuration connects BTCPay Server to Bitcoin Core already
running on the same Linux host instead of starting the bundled bitcoind
container. It does not configure Bitcoin Core or migrate an existing node.
This procedure only covers deployments without bundled Lightning. The bundled Lightning implementations expect the bundled Bitcoin service. Do not use this procedure to migrate a Lightning node with funds or channels.
Before continuing, configure Bitcoin Core so that:
- Its network matches
NBITCOIN_NETWORKin BTCPay Server. - Its RPC and P2P ports accept connections from the Docker network.
- A dedicated RPC username and strong password are available for NBXplorer.
- The RPC port is blocked from untrusted networks. Never expose Bitcoin Core RPC publicly.
Create
docker-compose-generator/docker-fragments/bitcoin.custom.yml with the
following content, replacing the ports and RPC credentials:
services:
btcpayserver:
environment:
BTCPAY_CHAINS: "btc"
BTCPAY_BTCEXPLORERURL: http://nbxplorer:32838/
nbxplorer:
environment:
NBXPLORER_CHAINS: "btc"
NBXPLORER_BTCRPCURL: http://host.docker.internal:43782/
NBXPLORER_BTCRPCUSER: "rpc-username"
NBXPLORER_BTCRPCPASSWORD: "rpc-password"
NBXPLORER_BTCNODEENDPOINT: host.docker.internal:39388
extra_hosts:
- "host.docker.internal:host-gateway"
required:
- nbxplorer
The required declaration keeps NBXplorer in the generated stack after the
standard bitcoin fragment is excluded. host-gateway resolves the Linux host
without relying on a particular Docker bridge address.
# Initial Deployment
Follow the installation guide up to, but not including,
the first . ./btcpay-setup.sh -i. Select the custom fragment and exclude the
standard Bitcoin fragment before running setup:
export BTCPAYGEN_EXCLUDE_FRAGMENTS="${BTCPAYGEN_EXCLUDE_FRAGMENTS:+${BTCPAYGEN_EXCLUDE_FRAGMENTS};}bitcoin;bitcoincore"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="${BTCPAYGEN_ADDITIONAL_FRAGMENTS:+${BTCPAYGEN_ADDITIONAL_FRAGMENTS};}bitcoin.custom"
. ./btcpay-setup.sh -i
The environment variables are necessary during initial deployment because
btcpay-fragments requires the saved deployment profile created by setup.
# Existing Deployment
Plan for Bitcoin payment processing to be briefly unavailable while changing fragments. Create the custom fragment first, verify that no bundled Lightning implementation is selected, then run as root:
btcpay-fragments exclude bitcoin bitcoincore
btcpay-fragments add bitcoin.custom
Each command reapplies setup. The first removes both the default and explicitly pinned Bitcoin Core fragments. The second adds the custom connection and restores NBXplorer. Confirm the effective selection and services afterward:
btcpay-fragments show
docker-compose -f "$BTCPAY_DOCKER_COMPOSE" config --services
The services must include btcpayserver and nbxplorer, and must not include
bitcoind. Check BTCPay Server's synchronization status before accepting
payments.
# Generate Without Installing
Set the complete generator selection and run build.sh from the repository
root:
BTCPAYGEN_CRYPTO1="btc" \
BTCPAYGEN_REVERSEPROXY="nginx" \
BTCPAYGEN_LIGHTNING="none" \
./build.sh
Unlike btcpay-setup.sh, direct build.sh use does not apply the setup
defaults, configure host SSH integration, or synchronize Nginx routes. The
setup and update scripts request those host changes explicitly with
--setup-ssh and --sync-routes. The output is
Generated/docker-compose.generated.yml; operate it explicitly with Docker
Compose and provide its runtime environment.
# Existing Reverse Proxy
For a standard installation behind an external reverse proxy, prefer the documented setup path in Networking instead of manually operating a custom generated stack.