Docker resources for hosting BTCPayServer easily
Switch branches/tags
Clone or download
Latest commit cb8cb70 Dec 14, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Rename docker files Nov 26, 2018
Generated acme.json related changes Sep 16, 2018
Production-NoReverseProxy fix doc for no reverse proxy Nov 16, 2018
Production Add spark integration Dec 12, 2018
Traefik update readmes Sep 30, 2018
contrib Add spark-wallet to the list of docker images Dec 12, 2018
docker-compose-generator bump nbxplorer Dec 14, 2018
.gitattributes generate-docker-compose should use docker, add .sh May 6, 2018
.gitignore add in gitignore traefik generated files Sep 25, 2018
LICENSE Init Sep 14, 2017
README.md Fix docker timeouts Dec 11, 2018
bgold-cli.ps1 Added Flag May 13, 2018
bgold-cli.sh Added Flag May 13, 2018
bgold-lncli.ps1 chmod +x Jul 20, 2018
bgold-lncli.sh chmod +x Jul 20, 2018
bitcoin-cli.ps1 Add utilities Mar 20, 2018
bitcoin-cli.sh Add utilities Mar 20, 2018
bitcoin-lightning-cli.ps1 Add cli tools Mar 21, 2018
bitcoin-lightning-cli.sh Add cli tools Mar 21, 2018
bitcoin-lncli.ps1 Fix macaroonpath for utilities Sep 29, 2018
bitcoin-lncli.sh Fix macaroonpath for utilities Sep 29, 2018
bitcore-cli.ps1 Add BTX support Dec 1, 2018
bitcore-cli.sh Add BTX support Dec 1, 2018
btcpay-down.sh Fix docker timeouts Dec 11, 2018
btcpay-restart.sh Fix docker timeouts Dec 11, 2018
btcpay-setclocale.sh change file name which bug updates Jun 6, 2018
btcpay-setup.sh Fix docker timeouts Dec 11, 2018
btcpay-up.sh Fix docker timeouts Dec 11, 2018
btcpay-update.sh Fix docker timeouts Dec 11, 2018
build.ps1 fix local generator Dec 7, 2018
build.sh fix local generator Dec 7, 2018
changedomain.sh Fix docker timeouts Dec 11, 2018
dash-cli.ps1 adjust dash datadir Nov 28, 2018
dash-cli.sh adjust dash datadir Nov 28, 2018
dogecoin-cli.ps1 Add chmod on dogecoin scripts Nov 27, 2018
dogecoin-cli.sh Add chmod on dogecoin scripts Nov 27, 2018
feathercoin-cli.ps1 Change permissions Jun 14, 2018
feathercoin-cli.sh Change permissions Jun 14, 2018
groestlcoin-cli.ps1 Add groestlcoin tooling Jun 24, 2018
groestlcoin-cli.sh Add groestlcoin tooling Jun 24, 2018
litecoin-cli.ps1 Add utilities Mar 20, 2018
litecoin-cli.sh Add utilities Mar 20, 2018
litecoin-lightning-cli.ps1 Add cli tools Mar 21, 2018
litecoin-lightning-cli.sh fix litecoin-lightning-cli Mar 21, 2018
litecoin-lncli.ps1 Fix macaroonpath for utilities Sep 29, 2018
litecoin-lncli.sh Fix macaroonpath for utilities Sep 29, 2018
monacoin-cli.ps1 support monacoin Nov 30, 2018
monacoin-cli.sh support monacoin Nov 30, 2018
publish-stable.ps1 helper script Jan 13, 2018
viacoin-cli.ps1 Viacoin support Jul 20, 2018
viacoin-cli.sh Viacoin support Jul 20, 2018

README.md

Start accepting Bitcoin today with BTCPayServer! This guide will walk you through the installation.

One-click deployment

For the easiest and fastest setup, host BTCPayServer on Microsoft Azure:

Deploy to Azure

You can log into Azure with your Microsoft account.

Final installation steps:

  • Fill in the options: Resource Group
  • Click 'Purchase' to confirm
  • (Wait for deployment)
  • View the deployment (in Notifications or Resource Groups)
  • Verify you can connect to your instance with a browser: https://SERVER-AZURE-DNS/
  • At your domain registrar, make sure you have DNS pointing your domain at your Azure deployment's IP.
  • Browse to https://SERVER-AZURE-DNS/
  • Register a new account (this account will be granted server administrator rights)
  • Go to https://SERVER-AZURE-DNS/server/maintenance
  • Enter your domain name and click on confirm
  • (Wait 1 to 5 minutes)

That's it, you can now browse to https://btcpay.YOUR-DOMAIN/ to create your store!

For advanced users, you can connect via SSH with information on https://btcpay.YOUR-DOMAIN/server/services/ssh, then you can:

  • Run docker ps and docker logs xxx to view running processes
  • Run btcpay-down.sh and btcpay-up.sh to stop and start the BTCPayServer

This video by Nicolas also demonstrates the above steps:

BTCPay - One Click Setup

Approximate Cost (unpruned, Bitcoin-only): 60 USD per month

After all your nodes have synced and you've confirmed everything works, follow this guide to fine-tune for savings; costs should drop to 30 or 40 USD per month.

Architecture

Architecture

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:

Note: The setup process can be time consuming, but is heavily automated to make it a fun and easy experience.

Full installation (for technical users)

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"
. ./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.

Docker automated build

Environment variables

btcpay-setup.sh will use the following environment variables:

  • BTCPAY_HOST: The hostname of your website (eg. btcpay.example.com)
  • NBITCOIN_NETWORK: The type of network to use (eg. mainnet, testnet, or regtest. Default: mainnet)
  • LIGHTNING_ALIAS: An alias for your lightning network node, if used
  • BTCPAYGEN_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 is Generated/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. me@example.com)
  • ACME_CA_URI: The API endpoint to ask for HTTPS certificate (Default: https://acme-v01.api.letsencrypt.org/directory)
  • BTCPAY_HOST_SSHKEYFILE: Optional, SSH private key that BTCPay can use to connect to this VM's SSH server. This key will be copied to BTCPay's data directory
  • BTCPAY_SSHTRUSTEDFINGERPRINTS: Optional, BTCPay will ensure that it is connecting to the expected SSH server by checking the host's public key against these fingerprints
  • BTCPAYGEN_DOCKER_IMAGE: Optional, Specify which generator image to use if you have customized the C# generator. Set to btcpayserver/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.

Tooling

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 BTCPayServer
  • btcpay-update.sh: Update BTCPayServer to the latest version
  • btcpay-up.sh: Run docker-compose up
  • btcpay-down.sh: Run docker-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

Under the hood

Generated docker-compose

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-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 plugin is maintained by JeffVandrewJr)

You can also create your own custom fragments.

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:

Again, what does btcpay-setup.sh do?

btcpay-setup.sh is a utility which does the following:

  1. Makes sure docker and docker-compose are installed on your system
  2. Generates a docker-compose via ./build.sh
  3. Sets up an Environment File to configure your docker-compose
  4. Sets up environment variables so the tools described in Tooling can work
  5. Adds symlinks of those tools into /usr/bin
  6. Makes sure BTCPay restarts on reboot via upstart or systemd
  7. Starts BTCPay via docker-compose

Overview of files generated by btcpay-setup.sh

/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 "$(dirname $BTCPAY_ENV_FILE)" && docker-compose -f "$BTCPAY_DOCKER_COMPOSE" up -d -t "${COMPOSE_HTTP_TIMEOUT:-180}"'
ExecStop=/bin/bash -c '. /etc/profile.d/btcpay-env.sh && cd "$(dirname $BTCPAY_ENV_FILE)" && docker-compose -f "$BTCPAY_DOCKER_COMPOSE" stop -t "${COMPOSE_HTTP_TIMEOUT:-180}"'
ExecReload=/bin/bash -c '. /etc/profile.d/btcpay-env.sh && cd "$(dirname $BTCPAY_ENV_FILE)" && docker-compose -f "$BTCPAY_DOCKER_COMPOSE" restart -t "${COMPOSE_HTTP_TIMEOUT:-180}"'

[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=me@EXAMPLE.com
BTCPAY_SSHTRUSTEDFINGERPRINTS=SHA256:eSCD7NtQ/Q6IBl2iRB9caAQ3lDZd8s8iUL6SdeNnhpA
BTCPAY_SSHKEYFILE=/datadir/id_rsa

How can I add an altcoin to BTCPayServer?

  1. Add support for your crypto to NBitcoin, NBxplorer, and BTCPayServer. (Use examples from other coins)
  2. Create your own docker image (Example for BTC)
  3. Create a docker-compose fragment (Example for BTC)
  4. 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.

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 want to add btg:

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

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

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

I'm getting an error on Windows: 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 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.

How I can prune my node(s)?

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.

How can I customize the generated docker-compose file?

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