aljaz/btcpayserver-docker
1
0
Fork 0
mirror of https://github.com/aljazceru/btcpayserver-docker.git synced 2026-02-05 20:54:30 +01:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Full read over readme.md: Grammar, formatting, and content fixes

Browse Source
This commit is contained in:
Jon Layton
2018-08-22 12:40:00 -05:00
parent bbb399aa7e
commit e5b96e8bab
1 changed files with 108 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
README.md
View File

@@ -1,50 +1,56 @@
# Introduction
This repository will help you to setup BTCPay and all its dependencies in a simple way:
This repository will help you install BTCPayServer, its environment, and all its dependencies.
![Architecture](https://github.com/btcpayserver/btcpayserver-doc/raw/master/img/Architecture.png)
As you can see, BTCPay depends on several piece of infrastructure, mainly:
As you can see, BTCPay depends on several pieces of infrastructure, mainly:
* A lightweight block explorer (NBXplorer),
* A database (Postgres, or SQLite),
* A full node (Bitcoin Core)
* A lightweight block explorer (NBXplorer),
* A database (PostgreSQL or SQLite),
* A full node (eg. 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.
There can be more dependencies if you support more than just standard Bitcoin transactions, including:
This repository is meant to setup your environment easily.
* [C-Lightning](https://github.com/ElementsProject/lightning)
* [LitecoinD](https://github.com/litecoin-project/litecoin) and other coin daemons
* And more...
# How to use this?
Note: The setup process can be time consuming, but is heavily automated to make it a fun and easy experience.
## For complete noobs
# How do I use this?
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
## One-click deployment
If you have no knowledge of Linux administration or Docker, we advise you to host BTCPay on Microsoft Azure:
First, [open an Azure account](https://azure.microsoft.com/en-us/account/), then:
[![Deploy to Azure](https://azuredeploy.net/deploybutton.svg)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fbtcpayserver%2Fbtcpayserver-azure%2Fmaster%2Fazuredeploy.json)
Follow this video
Follow this video for the remaining steps:
[![BTCPay - One Click Setup](http://img.youtube.com/vi/Bxs95BdEMHY/mqdefault.jpg)](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.
This installation is convenient, but will cost you around 60 USD per month (unpruned).
After all your nodes are synched and you confirm everything works, you can fine-tune (to save additional money) by following [this guide](https://github.com/btcpayserver/btcpayserver-doc/blob/master/PennyPinching.md); this will drop costs to 30 or 40 USD per month.
## For technical user
## For technical users
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.
You can also install BTCPayServer on your own machine or VPS instance.
First, make sure you have a domain name pointing to your host, with ports `443` and `80` externally accessible.
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`.
If you want to support litecoin, bitcoin and clightning and having HTTPS automatically configured by nginx.
If you want to support Litecoin, Bitcoin, and C-Lightning, and want HTTPS automatically configured by Nginx:
```bash
# Log as root
# Login as root
sudo su -
# Create a folder for BTCPay
mkdir BTCPayServer
mkdir BTCPayServer
cd BTCPayServer
# Clone this repository
@@ -60,9 +66,10 @@ export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_LIGHTNING="clightning"
. ./btcpay-setup.sh -i
exit
```
`btcpay-setup.sh` will :
`btcpay-setup.sh` will:
* Install Docker
* Install Docker-Compose
@@ -74,59 +81,62 @@ export BTCPAYGEN_LIGHTNING="clightning"
# Environment variables
`btcpay-setup.sh` will use the following environment variables:
* `BTCPAY_HOST`: The hostname of your website (eg. btcpay.example.com)
* `LETSENCRYPT_EMAIL`: A mail will be sent to this address if certificate expires and fail to renew automatically (eg. me@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, none. Default`: btc)
* `BTCPAYGEN_CRYPTO2`: Second supported crypto currency (eg. btc, ltc, none. Default`: empty)
* `BTCPAYGEN_CRYPTON`: N th supported crypto currency where N is maximum at maximum 9. (eg. btc, ltc. Default: none)
* `BTCPAYGEN_REVERSEPROXY`: Whether to use or not a reverse proxy. NGinx setup HTTPS for you. (eg. nginx, none. Default: nginx)
* `BTCPAYGEN_LIGHTNING`: Lightning network implementation to use (eg. clightning, none)
* `BTCPAYGEN_ADDITIONAL_FRAGMENTS`: Semi colon separated list of additional fragments you want to use (eg. `opt-save-storage`)
* `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 on BTCPay's data directory
# Tooling <a name="tooling"></a>
* `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`: Whether to use or not a reverse proxy. NGinx setup HTTPS for you. (eg. `nginx`, `(empty)`. Default: `nginx`)
* `BTCPAYGEN_LIGHTNING`: Lightning network implementation to use (eg. `clightning`, `(empty)`)
* `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 fail 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
A wide range of tooling get available on your system when btcpay is installed:
# Tooling
* `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-up.sh` Run docker-compose up
* `btcpay-down.sh` Run docker-compose down
* `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)
A wide variety of scripts are available once 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-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`: Setup your BTCPayServer
# Under the hood
## Generated docker-compose
Under the hood, your environment variable are used by [build.sh](build.sh) (or [build.ps1](build.ps1)) to generate a docker-compose adapted for your need.
By default, this script will generate `Generated/docker-compose.generated.yml`.
Under the hood, your environment variables are used by [build.sh](build.sh) (or [build.ps1](build.ps1)) to generate a docker-compose adapted for your needs.
The build script is generating the docker-compose by gluing together the relevant [docker fragment](docker-compose-generator/docker-fragments) for your setup.
By default, it will generate `Generated/docker-compose.generated.yml` by gluing together the relevant [Docker fragments](docker-compose-generator/docker-fragments) for your setup.
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_CRYPTO1` to `BTCPAYGEN_CRYPTO9`: Specify support for a crypto currency. (eg. `btc`, `ltc`)
* `BTCPAYGEN_REVERSEPROXY`: Specify the reverse proxy to use (eg. `nginx`, `none`)
* `BTCPAYGEN_LIGHTNING`: Specify the lightning network implementation (eg. `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`)
* `BTCPAYGEN_ADDITIONAL_FRAGMENTS`: Semi colon separated list of additional fragments you want to use, eg. `opt-save-storage`. (Default: empty)
* `BTCPAYGEN_ADDITIONAL_FRAGMENTS`: Semicolon-separated list of additional fragments you want to use, (eg. `opt-save-storage`, Default: `(empty)`)
Available `BTCPAYGEN_ADDITIONAL_FRAGMENTS` currently are:
* [opt-save-storage](docker-compose-generator/docker-fragments/opt-save-storage.yml) will keep around 1 year of blocks (prune BTC for 100 GB)
* [opt-save-storage-s](docker-compose-generator/docker-fragments/opt-save-storage-s.yml) will keep around 6 months of blocks (prune BTC for 50 GB)
* [opt-save-storage-xxs](docker-compose-generator/docker-fragments/opt-save-storage-xxs.yml) will keep around 2 weeks of blocks (prune BTC for 5 GB)
You can also create your [own fragments](#custom-fragments).
* [opt-save-storage-xxs](docker-compose-generator/docker-fragments/opt-save-storage-xxs.yml) will keep around 2 weeks of blocks (prune BTC for 5 GB) (lightning not supported)
You can also create your own [custom fragments](#how-can-i-customize-the-generated-docker-compose-file).
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.
Note: The first run might take a while, but following runs are instantaneous.
On Windows:
@@ -152,27 +162,28 @@ BTCPAYGEN_SUBNAME="custom" \
./build.sh
```
Next, you will need to configure the runtime environment variable for `Generated/docker-compose.custom.yml`.
Next, you will need to configure the runtime environment variables for `Generated/docker-compose.custom.yml`:
* If you are using [NGinx](Production/README.md)
* If you are [not using NGinx](Production-NoReverseProxy/README.md)
* If you are using NGinx, [read this](Production/README.md).
* If you are not using NGinx, [read this instead](Production-NoReverseProxy/README.md).
## What btcpay-setup do
## What does `btcpay-setup.sh` do?
`btcpay-setup.sh` utility is a tool which:
`btcpay-setup.sh` is a utility which does the following:
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.
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](https://docs.docker.com/compose/env-file/) to configure your docker-compose
4. Sets up environment variables so the tools described in [Tooling](#tooling) can work
5. Adds symbolic links of those tools in `/usr/bin`
6. Starts docker-compose
7. Makes sure it restarts at reboot via upstart or systemd
Here is an overview of the files generated by `btcpay-setup.sh`.
Here is an overview of the 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:
`/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"
@@ -202,7 +213,7 @@ export BTCPAY_SSHTRUSTEDFINGERPRINTS="$(cat $BTCPAY_ENV_FILE | sed -n 's/^BTCPAY
fi
```
`/etc/systemd/system/btcpayserver.service` file ensure that you can control btcpay via `systemctl`, and that btcpay server start on reboot:
`/etc/systemd/system/btcpayserver.service` ensures that you can control btcpay via `systemctl`, and that BTCPayServer starts on reboot:
```ini
[Unit]
@@ -222,7 +233,7 @@ ExecReload=/bin/bash -c '. /etc/profile.d/btcpay-env.sh && cd "$(dirname $BTCPAY
WantedBy=multi-user.target
```
`.env` file (`$BTCPAY_ENV_FILE`) are the environment variable passed to the containers managed by your docker-compose:
`.env` (`$BTCPAY_ENV_FILE`) contains environment variables passed to the containers managed by your docker-compose:
```ini
BTCPAY_HOST=btcpay.example.com
@@ -233,14 +244,14 @@ BTCPAY_SSHTRUSTEDFINGERPRINTS=SHA256:eSCD7NtQ/Q6IBl2iRB9caAQ3lDZd8s8iUL6SdeNnhpA
BTCPAY_SSHKEYFILE=/datadir/id_rsa
```
# How to extend with your own crypto?
# How can I add an altcoin to BTCPayServer?
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)
1. Add support for your crypto to [NBitcoin](https://github.com/MetacoSA/NBitcoin/tree/master/NBitcoin.Altcoins), [NBxplorer](https://github.com/dgarage/NBXplorer), and [BTCPayServer](https://github.com/btcpayserver/btcpayserver). (Use examples from 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))
4. Add your CryptoDefinition ([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.
Now if you want to test, **DO 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
@@ -250,80 +261,82 @@ cd docker-compose-generator/src
dotnet run
```
This will generate your docker-compose in the `Generated` folder, which you can then try by yourself.
This will generate your docker-compose in the `Generated` folder, which you can then try for yourself.
Note that BTCPayServer developers will not spend 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 wants to add `btg`.
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`:
```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"></a>
## I deployed before `btcpay-setup.sh` existed (before May 17), can I migrate to this new system?
Yes, the following command will migrate you to this new system:
Yes, run the following command to update:
```bash
sudo su -
btcpay-update.sh
cd $DOWNLOAD_ROOT/btcpayserver-docker
. ./btcpay-setup.sh -i
exit
```
## Windows user error: Cannot create container for service docker: Mount denied
## 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 command and run again `docker-compose -f <your.yml> up`.
Run this in powershell:
```powershell
$Env:COMPOSE_CONVERT_WINDOWS_PATHS=1
```
This bug comes from Docker for Windows and is [tracked on github](https://github.com/docker/for-win/issues/1829).
Then, run `docker-compose -f <your.yml> up`.
## How I can prune my nodes?
This bug comes from Docker for Windows and is [tracked on Github](https://github.com/docker/for-win/issues/1829).
This will prune your full node to keep maximum 100GB of blocks
## How I can prune my node(s)?
This will prune your Bitcoin full node to a maximum of 100GB (of blocks):
```bash
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage"
. ./btcpay-setup.sh -i
```
## The generated docker-compose is almost what I want... but not quite, how to customize? <a name="custom-fragments"></a>
Other options are `opt-save-storage-s` (50 GB), `opt-save-storage-xxs` (5 GB), or custom (see below).
In some instance, you might want to customize your environment in more details. Will you could modify `Generated/docker-compose.generated.yml` manually, your changes would be overwritten the next time you run `btcpay-update.sh`.
## How can I customize the generated docker-compose file?
Luckily, you can leverage `BTCPAYGEN_ADDITIONAL_FRAGMENTS` like this:
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`.
```bash
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage"
. ./btcpay-setup.sh -i
```
Luckily, you can leverage `BTCPAYGEN_ADDITIONAL_FRAGMENTS` for this!
[opt-save-storage](docker-compose-generator/docker-fragments/opt-save-storage.yml) will allow you to prune your node for targetting around 100 GB of space.
Let's enable **pruning to 60 GB**, for example:
But what if you want to target 5 GB of space (For example, if you do not need lightning)?
First, copy [opt-save-storage](docker-compose-generator/docker-fragments/opt-save-storage.yml) into the [the docker fragment folder](docker-compose-generator/docker-fragments) 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`.
First, Copy/Paste [opt-save-storage](docker-compose-generator/docker-fragments/opt-save-storage.yml) in the [the docker fragment folder](docker-compose-generator/docker-fragments) and name the file `opt-save-storage.custom.yml`. (Ending with `.custom.yml` is the important part, as it makes sure your fragment will not make a git conflict when you will run `btcpay-update.sh`)
Modify the new `opt-save-storage.custom.yml` file to your taste:
Then modify the file to your taste
```diff
@@ -14,8 +14,7 @@ version: "3"
services:
bitcoind:
environment:
- BITCOIN_EXTRA_ARGS: prune=100000
+ BITCOIN_EXTRA_ARGS: prune=5000
+ BITCOIN_EXTRA_ARGS: prune=60000
```
Then set it up: