# Optional Fragments
Manage optional fragments with btcpay-fragments. show is read-only; all
commands that change fragments must run as root. Changes are applied immediately
and multiple fragment names can be passed at once:
btcpay-fragments add opt-add-tor
btcpay-fragments remove opt-add-mempool
btcpay-fragments exclude btcpay-host
btcpay-fragments unexclude btcpay-host
btcpay-fragments show
show and successful changes return JSON containing the saved additional and
excluded fragments, the effective fragments from the last generated manifest,
and every fragment available in the current checkout. effectiveFragments is
empty before the first successful generation.
Adding a fragment removes it from the excluded set, and excluding one removes
it from the additional set. Every successful mutation command reapplies setup,
even when the requested fragment state is already satisfied. This also applies
other exported environment changes from the calling shell.
The fragment directory and btcpay-fragments show are authoritative for the
current checkout. This page is a curated operator catalog and may not describe
private custom fragments.
Dependencies and incompatibilities are resolved by the generator. Review each linked fragment before enabling third-party services; not every image supports every architecture or receives the same maintenance level.
# Resource Profiles
| Fragment | Purpose |
|---|---|
opt-save-storage (opens new window) | Prune supported nodes to about 100 GB |
opt-save-storage-s (opens new window) | Prune supported nodes to about 50 GB |
opt-save-storage-xs (opens new window) | Prune supported nodes to about 25 GB |
opt-save-storage-xxs (opens new window) | Prune supported nodes to about 5 GB; not recommended for Lightning, but not rejected by the generator |
opt-save-memory (opens new window) | Reduce daemon cache and mempool settings on hosts with less than 1 GB of memory |
opt-more-memory (opens new window) | Increase daemon cache when more than 1 GB can be dedicated to Bitcoin Core |
opt-txindex (opens new window) | Enable transaction indexing; incompatible with pruning |
opt-mempoolfullrbf (opens new window) | Enable Bitcoin Core full-RBF policy; recommended automatically for Bitcoin |
Only one pruning profile can be selected. The two memory profiles are mutually exclusive. Transaction indexing, ElectrumX, and the bundled Mempool service are incompatible with pruning.
# Lightning and Node Features
| Fragment | Purpose and requirements |
|---|---|
opt-lnd-autocompact (opens new window) | Enable LND database auto-compaction |
opt-lnd-autopilot (opens new window) | Enable LND autopilot with its configured limits |
opt-lnd-keysend (opens new window) | Enable LND keysend |
opt-lnd-watchtower (opens new window) | Enable the LND watchtower server and publish port 9911 |
opt-lnd-wtclient (opens new window) | Enable the LND watchtower client |
opt-add-zmq (opens new window) | Enable internal ZMQ endpoints for supported nodes |
opt-add-electrumx (opens new window) | Add public ElectrumX; requires txindex and an unpruned node |
opt-expose-unsafe (opens new window) | Publish Bitcoin P2P port 8333; trusted networks or restrictive firewall only |
opt-monero-expose (opens new window) | Bind Monero daemon RPC to host loopback |
opt-beldex-expose (opens new window) | Intended to bind Beldex RPC to host loopback; currently unsupported due to a service-name mismatch |
opt-decred-expose (opens new window) | Bind Decred wallet RPC to host loopback |
The LND tuning fragments affect a selected LND service; some do not declare a formal generator prerequisite, so confirm LND is enabled.
# Network Services
| Fragment | Purpose and requirements |
|---|---|
opt-add-tor (opens new window) | Add Tor hidden services and selected onion connectivity |
opt-add-cloudflared (opens new window) | Expose bundled Nginx through Cloudflare Tunnel and disable its local HTTPS companion; see the guide |
opt-add-tor-relay (opens new window) | Run a public non-exit relay on port 9001; requires contact details and legal review |
opt-add-pihole (opens new window) | Add Pi-hole DNS on TCP/UDP 53 for a trusted LAN; see the guide |
# Applications and Integrations
| Fragment | Purpose and requirements |
|---|---|
opt-add-btcqbo (opens new window) | Add the QuickBooks connector at /btcqbo/ |
opt-add-helipad (opens new window) | Add Podcasting 2.0 Helipad; requires Bitcoin LND |
opt-add-lightning-terminal (opens new window) | Add Lightning Terminal with a generated UI password; requires Bitcoin LND; see the guide |
opt-add-ltcmweb (opens new window) | Add the Litecoin MWEB plugin daemon; requires Litecoin |
opt-add-mempool (opens new window) | Add Mempool frontend/backend; requires ElectrumX, txindex, and an unpruned node |
opt-add-nostr-relay (opens new window) | Add a PostgreSQL-backed Nostr relay at /nostr |
opt-add-shopify (opens new window) | Add the internal Shopify app deployer |
opt-add-sphinxrelay (opens new window) | Add Sphinx Relay; requires Bitcoin LND and keysend |
opt-add-taler-merchant (opens new window) | Add the GNU Taler merchant backend |
opt-add-teos (opens new window) | Add a TEOS watchtower on port 9814; requires Bitcoin and ZMQ |
opt-add-thunderhub (opens new window) | Add ThunderHub; requires Bitcoin LND |
opt-add-woocommerce (opens new window) | Add WordPress and WooCommerce on a dedicated hostname |
opt-add-zammad (opens new window) | Add the Zammad application stack; requires substantial additional resources |
# Custom Fragments
For settings or services not represented here, create a .custom.yml fragment
instead of editing generated Compose output. See Customization.