While our instructions cover how to install BTCPayServer in one click on Azure or Lunanode, BTCPay Server is not limited to those options.
You will find below information about how you can install BTCPay Server easily in any environment having docker available.
As you can see, BTCPay depends on several pieces of infrastructure, mainly:
- A lightweight block explorer (NBXplorer),
- A database (PostgreSQL or SQLite),
- A full node (eg. Bitcoin Core)
There can be more dependencies if you support more than just standard Bitcoin transactions, including:
- C-Lightning
- LitecoinD and other coin daemons
- And more...
Note: The setup process can be time consuming, but is heavily automated to make it a fun and easy experience.
Take a look at how BTCPay works in a video below.
Here is a presentation of the global architecture at Advancing Bitcoin conference.
You can also install BTCPayServer on your own machine or VPS instance.
The officially supported setup is driven by Docker (and Docker-Compose).
First, make sure you have a domain name pointing to your host (CNAME), with ports 443
and 80
externally accessible (and perhaps additional ports like 9735
and 9736
for Bitcoin and Litecoin lightning). Otherwise, you will have to set it manually by running changedomain.sh
.
Let's assume it is btcpay.EXAMPLE.com
.
If you want to support Litecoin, Bitcoin, and C-Lightning, and want HTTPS automatically configured by Nginx:
# Login as root
sudo su -
# Create a folder for BTCPay
mkdir BTCPayServer
cd BTCPayServer
# Clone this repository
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker
# Run btcpay-setup.sh with the right parameters
export BTCPAY_HOST="btcpay.EXAMPLE.com"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_CRYPTO2="ltc"
export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_LIGHTNING="clightning"
export BTCPAY_ENABLE_SSH=true
. ./btcpay-setup.sh -i
exit
btcpay-setup.sh
will then:
- Install Docker
- Install Docker-Compose
- Make sure BTCPay starts at reboot via upstart or systemd
- Setup environment variables to use BTCPay utilities
- Add BTCPay utilities in /usr/bin
- Start BTCPay
You can read the article for step by step instructions.
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
, orregtest
. Default:mainnet
)LIGHTNING_ALIAS
: An alias for your lightning network node, if usedBTCPAYGEN_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
,(empty)
)BTCPAYGEN_SUBNAME
: The subname of the generated docker-compose file, where the full name isGenerated/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.[email protected]
)ACME_CA_URI
: The API endpoint to ask for HTTPS certificate (Default:https://acme-v01.api.letsencrypt.org/directory
)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 tobtcpayserver/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 nicknameTOR_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
)
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 BTCPayServerbtcpay-update.sh
: Update BTCPayServer to the latest versionbtcpay-up.sh
: Rundocker-compose up
btcpay-down.sh
: Rundocker-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
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.
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.
btcpay-setup.sh
is a utility which does the following:
- Makes sure docker and docker-compose are installed on your system
- Generates a docker-compose via
./build.sh
- Sets up an Environment File to configure your docker-compose
- Sets up environment variables so the tools described in Tooling can work
- Adds symlinks of those tools into
/usr/bin
- Makes sure BTCPay restarts on reboot via upstart or systemd
- Starts BTCPay via docker-compose
/etc/profile.d/btcpay-env.sh
ensures that your environment variables are correctly setup when you login, so you can use the tools:
export BTCPAYGEN_OLD_PREGEN="false"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_CRYPTO2=""
export BTCPAYGEN_CRYPTO3=""
export BTCPAYGEN_CRYPTO4=""
export BTCPAYGEN_CRYPTO5=""
export BTCPAYGEN_CRYPTO6=""
export BTCPAYGEN_CRYPTO7=""
export BTCPAYGEN_CRYPTO8=""
export BTCPAYGEN_CRYPTO9=""
export BTCPAYGEN_LIGHTNING="clightning"
export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS=""
export BTCPAY_DOCKER_COMPOSE="/var/lib/waagent/custom-script/download/0/btcpayserver-docker/Production/docker-compose.generated.yml"
export BTCPAY_BASE_DIRECTORY="/var/lib/waagent/custom-script/download/0"
export BTCPAY_ENV_FILE="/var/lib/waagent/custom-script/download/0/.env"
export BTCPAY_HOST_SSHKEYFILE="/root/.ssh/id_rsa_btcpay"
if cat $BTCPAY_ENV_FILE &> /dev/null; then
export $(grep -v '^#' "$BTCPAY_ENV_FILE" | xargs)
fi
/etc/systemd/system/btcpayserver.service
ensures that you can control btcpay via systemctl
, and that BTCPayServer starts on reboot:
[Unit]
Description=BTCPayServer service
After=docker.service network-online.target
Requires=docker.service network-online.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/bin/bash -c '. /etc/profile.d/btcpay-env.sh && cd "$BTCPAY_BASE_DIRECTORY/btcpayserver-docker" && . helpers.sh && btcpay_up'
ExecStop=/bin/bash -c '. /etc/profile.d/btcpay-env.sh && cd "$BTCPAY_BASE_DIRECTORY/btcpayserver-docker" && . helpers.sh && btcpay_down'
ExecReload=/bin/bash -c '. /etc/profile.d/btcpay-env.sh && cd "$BTCPAY_BASE_DIRECTORY/btcpayserver-docker" && . helpers.sh && btcpay_restart'
[Install]
WantedBy=multi-user.target
.env
($BTCPAY_ENV_FILE
) contains environment variables passed to the containers managed by your docker-compose:
BTCPAY_HOST=btcpay.EXAMPLE.com
ACME_CA_URI=https://acme-v01.api.letsencrypt.org/directory
NBITCOIN_NETWORK=mainnet
LETSENCRYPT_EMAIL[email protected]
BTCPAY_SSHTRUSTEDFINGERPRINTS=SHA256:eSCD7NtQ/Q6IBl2iRB9caAQ3lDZd8s8iUL6SdeNnhpA
BTCPAY_SSHKEYFILE=/datadir/id_rsa
- Add support for your crypto to NBitcoin, NBxplorer, and BTCPayServer. (Use examples from other coins)
- Create your own docker image (Example for BTC)
- Create a docker-compose fragment (Example for BTC)
- Add your
CryptoDefinition
(Example for BTC)
build.sh
is using a pre-built image of the docker-compose generator
on docker hub.
If you modify the code source of docker-compose generator
(for example, the CryptoDefinition
Example for BTC), you need to configure build.sh
to use your own image by setting the environment variable BTCPAYGEN_DOCKER_IMAGE
to btcpayserver/docker-compose-generator:local
.
cd docker-compose-generator
BTCPAYGEN_DOCKER_IMAGE="btcpayserver/docker-compose-generator:local"
Or on powershell:
cd docker-compose-generator
$BTCPAYGEN_DOCKER_IMAGE="btcpayserver/docker-compose-generator:local"
Then run ./build.sh
or . .\build.ps1
.
This will generate your docker-compose in the Generated
folder, which you can then run and test.
Note that BTCPayServer developers will not spend excessive time testing your image, so make sure it works.
We are trying to update our dependencies to run on arm32v7
and x64
boards. Here is our progress:
Source | Image | Version | x64 | arm32v7 | arm64v8 | links |
---|---|---|---|---|---|---|
* | btcpayserver/docker-compose-generator | latest | ✔️ | ✔️ | ✔️ | Github - DockerHub |
* | btcpayserver/docker-compose-builder | 1.24.1 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
bitcoin.yml | btcpayserver/bitcoin | 0.18.0 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
bitcoin-clightning.yml | btcpayserver/lightning | v0.7.2-1 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
bitcoin-clightning.yml | shesek/lightning-charge | 0.4.6-standalone | ✔️ | ️❌ | ️❌ | Github - DockerHub |
bitcoin-clightning.yml | shesek/spark-wallet | 0.2.8-standalone | ✔️ | ️❌ | ️❌ | Github - DockerHub |
bitcoin-lnd.yml | btcpayserver/lnd | v0.7.1-beta | ✔️ | ✔️ | ✔️ | Github - DockerHub |
bitcore.yml | dalijolijo/docker-bitcore | 0.15.2 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
btcpayserver.yml | btcpayserver/btcpayserver | 1.0.3.133 | ✔️ | ✔️ | ️❌ | Github - DockerHub |
dash.yml | btcpayserver/dash | 0.14.0.1 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
dogecoin.yml | rockstardev/dogecoin | 1.10.0 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
feathercoin.yml | chekaz/docker-feathercoin | 0.16.3 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
groestlcoin.yml | nicolasdorier/docker-groestlcoin | 2.17.2 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
groestlcoin-clightning.yml | groestlcoin/lightning | v0.7.2 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
groestlcoin-clightning.yml | groestlcoin/groestlcoin-lightning-charge | version-0.4.9 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
groestlcoin-clightning.yml | groestlcoin/groestlcoin-spark | version-0.2.8 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
litecoin.yml | btcpayserver/litecoin | 0.17.1-1 | ✔️ | ✔️ | ️❌ | Github - DockerHub |
litecoin-clightning.yml | btcpayserver/lightning | v0.7.2-1 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
litecoin-lnd.yml | btcpayserver/lnd | v0.7.1-beta | ✔️ | ✔️ | ✔️ | Github - DockerHub |
monacoin.yml | wakiyamap/docker-monacoin | 0.16.3 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
monero.yml | kukks/monero | v0.14.1.2 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
monero.yml | kukks/monero | v0.14.1.2 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
nbxplorer.yml | nicolasdorier/nbxplorer | 2.0.0.57 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
nginx.yml | nginx | 1.16.0 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
nginx.yml | btcpayserver/docker-gen | 0.7.6 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
nginx-https.yml | btcpayserver/letsencrypt-nginx-proxy-companion | 1.11.2.1 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
opt-add-btcqbo.yml | jvandrew/btcqbo | 0.3.36 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
opt-add-btcqbo.yml | redis | 5.0.2-alpine | ✔️ | ️❌ | ️❌ | Github - DockerHub |
opt-add-btctransmuter.yml | btcpayserver/btctransmuter | 0.0.37 | ✔️ | ✔️ | ️❌ | Github - DockerHub |
opt-add-librepatron.yml | jvandrew/librepatron | 0.7.39 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
opt-add-librepatron.yml | jvandrew/isso | atron.22 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
opt-add-tor.yml | btcpayserver/tor | 0.4.1.5 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
opt-add-tor.yml | btcpayserver/docker-gen | 0.7.6 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
opt-add-tor-relay.yml | btcpayserver/docker-gen | 0.7.6 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
opt-add-tor-relay.yml | btcpayserver/tor | 0.4.1.5 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
opt-add-woocommerce.yml | btcpayserver/docker-woocommerce | 3.0.6-3 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
opt-add-woocommerce.yml | mariadb | 10.3 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
postgres.yml | postgres | 9.6.5 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
traefik.yml | traefik | latest | ✔️ | ️❌ | ️❌ | Github - DockerHub |
trezarcoin.yml | chekaz/docker-trezarcoin | 0.13.0 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
viacoin.yml | romanornr/docker-viacoin | 0.15.2 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
bgold.yml | kamigawabul/docker-bitcoingold | 0.15.2 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
bgold-lnd.yml | kamigawabul/btglnd | latest | ✔️ | ️❌ | ️❌ | Github - DockerHub |
bitcoin-lnd.yml | shahanafarooqui/rtl | 0.5.1 | ✔️ | ✔️ | ✔️ | Github - DockerHub |
bitcoinplus.yml | chekaz/docker-bitcoinplus | 2.7.0 | ✔️ | ️❌ | ️❌ | Github - DockerHub |
As root, run . btcpay-setup.sh
; this will show you the environment variable it is expecting.
For example, if you support btc
and ltc
already, and want to add btg
:
export BTCPAYGEN_CRYPTO3='btg'
. btcpay-setup.sh -i
Yes, run the following commands to update:
sudo su -
cd $DOWNLOAD_ROOT/btcpayserver-docker
git checkout master
git pull
git checkout 9acb5d8067cb5c46f59858137feb699b41ac9f19
btcpay-update.sh
. ./btcpay-setup.sh -i
git checkout master
btcpay-update.sh
exit
If you see this error:
Cannot create container for service docker: b'Mount denied:\nThe source path "\\\\var\\\\run\\\\docker.sock:/var/run/docker.sock"\nis not a valid Windows path'
.
Run this in powershell:
$Env:COMPOSE_CONVERT_WINDOWS_PATHS=1
Then, run docker-compose -f EXAMPLE.yml up
.
This bug comes from Docker for Windows and is tracked on Github.
This will prune your Bitcoin full node to a maximum of 100GB (of blocks):
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage"
. ./btcpay-setup.sh -i
Other options are documented here.
In some instances, you might want to customize your environment in more detail. While you could modify Generated/docker-compose.generated.yml
manually, your changes would be overwritten the next time you run btcpay-update.sh
.
Luckily, you can leverage BTCPAYGEN_ADDITIONAL_FRAGMENTS
for this!
Let's enable pruning to 60 GB, for example:
First, copy opt-save-storage into the the docker fragment folder as opt-save-storage.custom.yml
. Important: the file must end with .custom.yml
, or there will be git conflicts whenever you run btcpay-update.sh
.
Modify the new opt-save-storage.custom.yml
file to your taste:
@@ -14,8 +14,7 @@ version: "3"
services:
bitcoind:
environment:
- BITCOIN_EXTRA_ARGS: prune=100000
+ BITCOIN_EXTRA_ARGS: prune=60000
Then set it up:
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage.custom"
. ./btcpay-setup.sh -i
You can change the ports for HTTP and HTTPS by setting the environment variables REVERSEPROXY_HTTP_PORT
and REVERSEPROXY_HTTPS_PORT
. This is handy when ports 80 and 443 are already in use on your host, or you want to offload SSL termination with an existing web proxy.
When you set REVERSEPROXY_HTTP_PORT
to another value than 80, the built-in Let's Encrypt certificate will not work, as Let's Encrypt will try to validate your SSL certificate request by connecting from the internet to your domain on port 80. This validation request should be able to reach BTCPay Server in order to receive the certificate.
If you need to run on a different port, it's best to terminate SSL using another web proxy and forward your traffic.
Yes. To offload SSL termination, just forward the requests to the port specified by REVERSEPROXY_HTTP_PORT
and make sure you are setting the header X-Forwarded-Proto: https
so BTC Pay Server can know the original request was HTTPS. If you forget this extra header, BTCPay Server will work, but it will believe the connection is insecure and display a warning message.
Because you are offloading HTTPS, you won't need the built-in Let's Encrypt anymore and can exclude nginx-https
by adding it to BTCPAYGEN_EXCLUDE_FRAGMENTS
.