mirror of
https://github.com/aljazceru/btcpayserver-docker.git
synced 2026-01-20 15:34:35 +01:00
284 lines
11 KiB
Markdown
284 lines
11 KiB
Markdown
# 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
|
|
|
|
[](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fbtcpayserver%2Fbtcpayserver-azure%2Fmaster%2Fazuredeploy.json)
|
|
|
|
Follow this video
|
|
|
|
[](http://www.youtube.com/watch?v=Bxs95BdEMHY "BTCPay - One Click Setup")
|
|
|
|
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](https://github.com/btcpayserver/btcpayserver-doc/blob/master/PennyPinching.md), 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.
|
|
|
|
```bash
|
|
# 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 name="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](Production) `docker-compose` files are used for production environment. It adds NGinx as a reverse proxy and [Let's Encrypt and DockerGen](https://github.com/gilyes/docker-nginx-letsencrypt-sample) 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:
|
|
|
|
[](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fbtcpayserver%2Fbtcpayserver-azure%2Fmaster%2Fazuredeploy.json)
|
|
|
|
The [Production-NoReverseProxy](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](Production) and [Production-NoReverseProxy](Production-NoReverseProxy) are generated by running the [build-pregen.sh](build-pregen.sh) (or [build-pregen.ps1](build-pregen.ps1)) scripts from the fragments located in [docker-compose-generator/docker-fragments](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](build.sh) (or [build.ps1](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](build.sh) (or [build.ps1](build.ps1)) will then generate a `docker-compose.generated.yml` in the [Generated](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](https://docs.docker.com/compose/env-file/) to configure your docker-compose
|
|
4. Setup environment variables so the tools described in [tooling](#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.
|
|
```bash
|
|
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:
|
|
|
|
```ini
|
|
[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:
|
|
|
|
```ini
|
|
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](https://github.com/MetacoSA/NBitcoin/tree/master/NBitcoin.Altcoins)/[NBxplorer](https://github.com/dgarage/NBXplorer)/[BTCPay Server](https://github.com/btcpayserver/btcpayserver). (Take example on other coins)
|
|
2. Create your own docker image ([Example for BTC](https://hub.docker.com/r/nicolasdorier/docker-bitcoin/))
|
|
3. Create a docker-compose fragment ([Example for BTC](docker-compose-generator/docker-fragments/bitcoin.yml))
|
|
4. Add your Crypto Definition ([Example for BTC](docker-compose-generator/src/CryptoDefinition.cs))
|
|
|
|
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](https://www.microsoft.com/net/download/windows) then run:
|
|
|
|
```bash
|
|
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 <a name="fornoobs" />
|
|
|
|
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](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`.
|
|
|
|
```bash
|
|
export BTCPAYGEN_CRYPTO3='btg'
|
|
. btcpay-setup.sh -i
|
|
```
|
|
|
|
## I deployed before btcpay-setup.sh existed, can I migrate to this new system? <a name="migration" />
|
|
|
|
Yes, the following command will migrate you to this new system:
|
|
|
|
```bash
|
|
sudo su -
|
|
btcpay-update.sh
|
|
cd $DOWNLOAD_ROOT/btcpayserver-docker
|
|
. ./btcpay-setup.sh -i
|
|
```
|