Migration to new deployment system
This commit is contained in:
nicolas.dorier
283
README.md
283
README.md
@@ -1,16 +1,91 @@
|
||||
# How to use
|
||||
# Introduction
|
||||
|
||||
This repository is hosting different docker-compose which can be used to facilitate deployment of BTCPay Server.
|
||||
This repository will help you to setup BTCPay and all its dependencies in a simple way:
|
||||
|
||||
|
||||
|
||||
As you can see, it depends on several piece of infrastructure, mainly:
|
||||
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)
|
||||
|
||||
Setting up the dependencies might be time consuming, this repository is meant to give working example of `docker-compose` file which will setup everything for you.
|
||||
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 clighning 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.
|
||||
|
||||
@@ -20,23 +95,140 @@ The production `docker-compose` is used under the hood to deploy an instance of
|
||||
|
||||
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.
|
||||
|
||||
# About accessing services inside those docker compose
|
||||
## Generated docker-compose
|
||||
|
||||
Several scripts are provided to access the internal of your docker-service:
|
||||
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).
|
||||
|
||||
* `litecoin-cli.sh`
|
||||
* `bitcoin-cli.sh`
|
||||
* `litecoin-lightning-cli.sh`
|
||||
* `bitcoin-lightning-cli.sh`
|
||||
The pre-generated `docker-compose` files cover `btc`, `ltc`, `clightning` for configuration with or without `nginx `reverse proxy.
|
||||
|
||||
We also provide powershell `.ps1` scripts if you are on windows.
|
||||
If you want any other configuration, you need to run [build.sh](build.sh) (or [build.ps1](build.ps1)) with environment variables correctly set.
|
||||
|
||||
You can use it easily:
|
||||
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:
|
||||
|
||||
```
|
||||
./bitcoin-cli.sh getblockcount
|
||||
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.
|
||||
@@ -67,60 +259,25 @@ 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/`.
|
||||
|
||||
# About generate-docker-compose
|
||||
# FAQ
|
||||
|
||||
The files in `Production` and `Production-NoReverseProxy` are generated by a dotnet program located in `docker-compose-generator`.
|
||||
It is meant to generate a wide range a configuration from `docker-compose-generator/docker-fragments` without repeating myself.
|
||||
## How can I modify my environment?
|
||||
|
||||
# No docker-compose suit my need, what should I do?
|
||||
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`.
|
||||
|
||||
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 root folder of this repository.
|
||||
For example, if you want `btc` and `ltc` support with `nginx` and `clightning` inside `Generate/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
|
||||
}
|
||||
```bash
|
||||
export BTCPAYGEN_CRYPTO3='btg'
|
||||
. btcpay-setup.sh -i
|
||||
```
|
||||
|
||||
On Linux:
|
||||
## I deployed before btcpay-setup.sh existed, can I migrate to this new system? <a name="migration" />
|
||||
|
||||
```
|
||||
BTCPAYGEN_CRYPTO1="btc" \
|
||||
BTCPAYGEN_CRYPTO2="ltc" \
|
||||
BTCPAYGEN_REVERSEPROXY="nginx" \
|
||||
BTCPAYGEN_LIGHTNING="clightning" \
|
||||
BTCPAYGEN_SUBNAME="custom" \
|
||||
./build.sh
|
||||
```
|
||||
Yes, the following command will migrate you to this new system:
|
||||
|
||||
# How to extend with my 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))
|
||||
|
||||
Congratulation!
|
||||
```bash
|
||||
sudo su -
|
||||
btcpay-update.sh
|
||||
cd $DOWNLOAD_ROOT/btcpayserver-docker
|
||||
. ./btcpay-setup.sh -i
|
||||
```
|
||||
Reference in New Issue
Block a user