Introduction

This repository will help you to setup BTCPay and all its dependencies in a simple way:

As you can see, BTCPay depends on several piece of infrastructure, mainly:

• A lightweight block explorer (NBXplorer),
• A database (Postgres, or SQLite),
• A full node (Bitcoin Core)

There is more dependencies, if you support more than just Bitcoin. (C-Lightning, LitecoinD etc...) Setting up the dependencies correctly in a production environment might be time consuming.

This repository is meant to setup your environment easily.

How to use this?

For complete noobs

If you have no knowledge of Linux administration or Docker, we advise you to host BTCPay on Microsoft Azure by opening an account then clicking here

Follow this video

This installation is convenient but will cost you around 60 USD per month. After all your nodes are synched and you confirm things work fine, you can fine tune save additional money by following this guide, and drop to 30 or 40 USD per month.

For technical user

If, for some reason, you don't want or can't use the Azure deployment explained above then you can install BTCPayServer on your own instance.

First step is to make sure you have a domain name pointing to your host, and that port 443 and 80 and externally accessible. Let's assume it is btcpay.example.com.

You also want to support litecoin, bitcoin and clightning and having HTTPS automatically configured by nginx.

# Log 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"
. ./btcpay-setup.sh -i

btcpay-setup.sh will :

• 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

Tooling

A wide range of tooling get available on your system when btcpay is installed:

• bitcoin-cli.sh access your bitcoin node instance
• bitcoin-lightning-cli.sh access your clightning node instance
• changedomain.sh change the domain of your BTCPayServer
• btcpay-update.sh update BTCPay to the latest version
• btcpay-setup.sh change the settings of your server (run . ./btcpay-setup.sh to get more information about additional parameters, run . ./btcpay-setup.sh -i to setup again your btcpay server)

Under the hood

Prebuilt docker-compose

For your custom need, you will find some working example of docker-compose file which will setup everything for you.

The Production docker-compose files are used for production environment. It adds NGinx as a reverse proxy and Let's Encrypt and DockerGen to automatically configure HTTPS.

The production docker-compose is used under the hood to deploy an instance of BTCPay on Microsoft Azure in one click:

The Production-NoReverseProxy docker-compose files are used for environment which are already behind a reverse proxy. It exposes BTCPayServer directly on port 80.

Generated docker-compose

All docker-compose files in Production and Production-NoReverseProxy are generated by running the build-pregen.sh (or build-pregen.ps1) scripts from the fragments located in docker-compose-generator/docker-fragments.

The pre-generated docker-compose files cover btc, ltc, clightning for configuration with or without nginx reverse proxy.

If you want any other configuration, you need to run build.sh (or build.ps1) with environment variables correctly set.

To configure your custom docker-compose, the following environment variables are supported:

• BTCPAYGEN_CRYPTO1 to BTCPAYGEN_CRYPTO9: Specify support for a crypto currency. (Valid value: btc, ltc)
• BTCPAYGEN_REVERSEPROXY: Specify the reverse proxy to use (Valid value: nginx, none)
• BTCPAYGEN_LIGHTNING: Specify the lightning network implementation (Valid value: clightning, none)
• BTCPAYGEN_SUBNAME: The sub name of the generated docker-compose file, where the full name will be Generated/docker-compose.SUBNAME.yml (Default: generated)

Then, running build.sh (or build.ps1) will then generate a docker-compose.generated.yml in the Generated folder of this repository.

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 next run are instantaneous.

On Windows:

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

What btcpay-setup do

btcpay-setup.sh utility is a tool which:

1. Make sure docker and docker-compose are installed on your system
2. Generate a docker-compose via ./build.sh
3. Setup an Environment File to configure your docker-compose
4. Setup environment variables so the tools described in tooling can work.
5. Add symbolic links of those tools in /usr/bin
6. Start docker-compose
7. Make sure it restart at reboot via upstart or systemd.

Here is an overview of the files generated by btcpay-setup.sh.

/etc/profile.d/btcpay-env.sh ensures that your environment variable are correctly setup when you log in, 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 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"
if cat $BTCPAY_ENV_FILE &> /dev/null; then
export BTCPAY_HOST="$(cat $BTCPAY_ENV_FILE | sed -n 's/^BTCPAY_HOST=\(.*\)$/\1/p')"
export LETSENCRYPT_EMAIL="$(cat $BTCPAY_ENV_FILE | sed -n 's/^LETSENCRYPT_EMAIL=\(.*\)$/\1/p')"
export NBITCOIN_NETWORK="$(cat $BTCPAY_ENV_FILE | sed -n 's/^NBITCOIN_NETWORK=\(.*\)$/\1/p')"
export LIGHTNING_ALIAS="$(cat $BTCPAY_ENV_FILE | sed -n 's/^LIGHTNING_ALIAS=\(.*\)$/\1/p')"
export ACME_CA_URI="$(cat $BTCPAY_ENV_FILE | sed -n 's/^ACME_CA_URI=\(.*\)$/\1/p')"
fi

/etc/systemd/system/btcpayserver.service file ensure that you can control btcpay via systemctl, and that btcpay server start 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 "$(dirname $BTCPAY_ENV_FILE)" && docker-compose -f "$BTCPAY_DOCKER_COMPOSE" up -d'
ExecStop=/bin/bash -c '. /etc/profile.d/btcpay-env.sh && cd "$(dirname $BTCPAY_ENV_FILE)" && docker-compose -f "$BTCPAY_DOCKER_COMPOSE" stop'
ExecReload=/bin/bash -c '. /etc/profile.d/btcpay-env.sh && cd "$(dirname $BTCPAY_ENV_FILE)" && docker-compose -f "$BTCPAY_DOCKER_COMPOSE" restart'

[Install]
WantedBy=multi-user.target

.env file ($BTCPAY_ENV_FILE) are the environment variable 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=me@example.com

How to extend with your own crypto?

1. Support for your crypto on NBitcoin/NBxplorer/BTCPay Server. (Take example on other coins)
2. Create your own docker image (Example for BTC)
3. Create a docker-compose fragment (Example for BTC)
4. Add your Crypto Definition (Example for BTC)

Now if you want to test, DOT NOT USE build.sh, because this utility is a pre-built docker image. Instead, install .NET Core 2.1 SDK then run:

BTCPAYGEN_CRYPTO1="xxx"
BTCPAYGEN_SUBNAME="test"
cd docker-compose-generator/src
dotnet run

This will generate your docker-compose in the Generated folder, which you can then try by yourself. Note that BTCPayServer developers will not spend time testing your image, so make sure it works.

For docker noobs

If you are a docker noob here is how you would create a HTTPS ready server.

First step is to make sure you have a domain name pointing to your host, and that port 443 and 80 and externally accessible. Let's assume it is btcpay.example.com.

Clone the repository:

git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker

Create an .env file with the parameters documented in Production:

NBITCOIN_NETWORK=mainnet
BTCPAY_HOST=btcpay.example.com
LETSENCRYPT_EMAIL=me@example.com
ACME_CA_URI=https://acme-v01.api.letsencrypt.org/directory

Save, then run it:

docker-compose -f "$(pwd)/Production/docker-compose.btc-ltc.yml" up -d

Wait a little bit, then you can now browse https://btcpay.example.com/.

FAQ

How can I modify my environment?

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 wants to add btg.

export BTCPAYGEN_CRYPTO3='btg'
. btcpay-setup.sh -i

I deployed before btcpay-setup.sh existed, can I migrate to this new system?

Yes, the following command will migrate you to this new system:

sudo su -
btcpay-update.sh
cd $DOWNLOAD_ROOT/btcpayserver-docker
. ./btcpay-setup.sh -i

Windows user error: Cannot create container for service docker: Mount denied

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 command and run again docker-compose -f <your.yml> up.

$Env:COMPOSE_CONVERT_WINDOWS_PATHS=1

This bug comes from Docker for Windows and is tracked on github.