BTCPayServer

BTCPayServer

Official

Docker app from Raccommode's Repository

Overview

BTCPay Server is a free and open-source Bitcoin payment processor for self-hosted stores, invoices, checkout, wallets, point-of-sale flows, plugins, and webhooks without third-party payment processor fees.

Readme

View on GitHub

BTCPay Server Docker Documentation

This documentation covers the official Docker deployment of BTCPay Server. For product usage, stores, wallets, and integrations, see the BTCPay Server documentation.

Get Started

  • Installation: requirements, the production deployment path, and what the setup script changes on the host
  • Server specifications: size CPU, memory, storage, and bandwidth for selected chains and features
  • Architecture: required components, data flow, generated files, and optional services

Configure the Stack

  • Configuration: environment variables and storage or memory profiles
  • Networking: domains, ports, HTTPS, reverse proxies, tunnels, and optional Nginx routes
  • Lightning: choosing and enabling CLN, LND, or Phoenixd
  • Cryptocurrencies: selecting supported chains and understanding support boundaries
  • Optional fragments: the catalog of optional stack features

Operate and Maintain

  • Operations: service lifecycle, command-line tools, logs, and database access
  • Updating: updating the repository and stack, archived update logs, and image cleanup
  • Backup and restore: creating, encrypting, and restoring deployment backups
  • Troubleshooting: infrastructure checks and diagnostics to collect before requesting help

Customize and Develop

  • Customization: generated Compose files and custom fragments
  • Development: generator development and adding a new cryptocurrency

Optional Services

The fragment catalog lists every available optional fragment, including features that do not require a separate guide.

Build Provenance

Help

Use the BTCPay Server community chat for deployment questions. Report reproducible defects in the Docker tooling on the btcpayserver-docker issue tracker.

Media gallery

Requirements

This template runs the BTCPay Server application container only. The officially supported deployment is a Docker Compose stack with Postgres, NBXplorer, and a Bitcoin full node, plus optional reverse proxy and Lightning services. Configure those services separately and point the Postgres, Explorer, and Bitcoin variables below at them before using BTCPay with real funds. If using container names such as postgres or nbxplorer, place all containers on the same custom Docker network.

Categories

Network > OtherTools > Utilities

Download Statistics

4,113,808
Total Downloads
28,949
This Month
17,192
Avg / Month

Total Downloads Over Time

Loading chart...

Related apps

Explore more like this

Explore all
Other appsUtilities apps

Links

Projectgithub.comSupportgithub.comDocker Hubhub.docker.comTemplateraw.githubusercontent.com

Details

Repository
btcpayserver/btcpayserver:latest
Registry
https://hub.docker.com/r/btcpayserver/btcpayserver
Last Updated2026-10-06
First Seen2026-06-05

Runtime arguments

Web UI
http://[IP]:[PORT:49392]
Network
bridge
Shell
sh
Privileged
false

Template configuration

Web UI PortPorttcp

BTCPay Server web interface and internal API port. Container port: 49392.

Target
49392
Default
49392
Value
49392
DataPathrw

Persistent BTCPay Server data directory. Back this directory up before processing real payments.

Target
/datadir
Default
/mnt/user/appdata/btcpayserver
Value
/mnt/user/appdata/btcpayserver
PluginsPathrw

Persistent BTCPay Server plugins directory.

Target
/root/.btcpayserver/Plugins
Default
/mnt/user/appdata/btcpayserver/plugins
Value
/mnt/user/appdata/btcpayserver/plugins
Bind AddressVariable

Address and port BTCPay binds to inside the container.

Target
BTCPAY_BIND
Default
0.0.0.0:49392
Value
0.0.0.0:49392
NetworkVariable

Bitcoin network. Use mainnet, testnet, signet, or regtest.

Target
BTCPAY_NETWORK
Default
mainnet
Value
mainnet
ChainsVariable

Comma-separated crypto chains enabled in BTCPay. This template defaults to Bitcoin only.

Target
BTCPAY_CHAINS
Default
btc
Value
btc
Public HostVariable

Optional public hostname, for example btcpay.example.com. Use a reverse proxy for HTTPS when exposing BTCPay outside your LAN.

Target
BTCPAY_HOST
Root PathVariable

BTCPay root path when served from a subpath. Use / for normal deployments.

Target
BTCPAY_ROOTPATH
Default
/
Value
/
Postgres ConnectionVariable

Required Postgres connection string for the BTCPay Server database.

Target
BTCPAY_POSTGRES
Default
User ID=postgres;Host=postgres;Port=5432;Application Name=btcpayserver;Database=btcpayservermainnet
Value
User ID=postgres;Host=postgres;Port=5432;Application Name=btcpayserver;Database=btcpayservermainnet
Explorer Postgres ConnectionVariable

Required Postgres connection string for NBXplorer data, used by BTCPay to read explorer state.

Target
BTCPAY_EXPLORERPOSTGRES
Default
User ID=postgres;Host=postgres;Port=5432;Application Name=btcpayserver;MaxPoolSize=80;Database=nbxplorermainnet
Value
User ID=postgres;Host=postgres;Port=5432;Application Name=btcpayserver;MaxPoolSize=80;Database=nbxplorermainnet
BTC Explorer URLVariable

Required NBXplorer URL for Bitcoin, for example http://nbxplorer:32838/ on a custom Docker network or http://UNRAID-IP:32838/.

Target
BTCPAY_BTCEXPLORERURL
Default
http://nbxplorer:32838/
Value
http://nbxplorer:32838/
Docker Deployment ModeVariable

Marks this BTCPay instance as Docker-deployed. Use true or false.

Target
BTCPAY_DOCKERDEPLOYMENT
Default
true
Value
true
No Default ChainVariable

Prevents BTCPay from assuming a chain without explicit chain variables. Use true or false.

Target
BTCPAY_NODEFAULTCHAIN
Default
true
Value
true
Update URLVariable

Release URL used by BTCPay to check for new versions.

Target
BTCPAY_UPDATEURL
Default
https://api.github.com/repos/btcpayserver/btcpayserver/releases/latest
Value
https://api.github.com/repos/btcpayserver/btcpayserver/releases/latest
Debug LogVariable

Debug log filename under the BTCPay data directory.

Target
BTCPAY_DEBUGLOG
Default
btcpay.log
Value
btcpay.log
Lightning ConnectionVariable

Optional Bitcoin Lightning connection string. For example, type=clightning;server=unix://etc/clightning_bitcoin/lightning-rpc, or leave blank to configure later in BTCPay.

Target
BTCPAY_BTCLIGHTNING