From 7cd1bf779ec1c23c4c85535ac249e5699cd9c8ac Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Mon, 15 Sep 2025 13:45:38 -0500 Subject: [PATCH 01/12] Create save-env-vars.md Instructions for how to save your env vars to a source file which can be reloaded to your session without pasting individual lines or remembering what configs you modified when you first set up the server. --- docs/save-env-vars.md | 112 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/save-env-vars.md diff --git a/docs/save-env-vars.md b/docs/save-env-vars.md new file mode 100644 index 000000000..0dd1d5b34 --- /dev/null +++ b/docs/save-env-vars.md @@ -0,0 +1,112 @@ +# Save Environment Variables to Script + +Environment Variables are lost upon logging out of the server. This means that any change to our config requires us to export ALL variables again before running `. ./btcpay-setup.sh -i`. + +One solution to this might be simply saving your config as a `.txt` file and copying over from there, but this does not alleviate us of the manual labor of pasting each line. + +My solution: save them as a script that we will run using `source` before runnning `btcpay-setup.sh`. + +## Basic Way +From the [main docker deployment page](./README.md#full-installation-for-technical-users) our initial setup will look like this: + +```bash +# 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_ADDITIONAL_FRAGMENTS="opt-save-storage-s" +export BTCPAYGEN_REVERSEPROXY="nginx" +export BTCPAYGEN_LIGHTNING="clightning" +export BTCPAY_ENABLE_SSH=true +. ./btcpay-setup.sh -i + +exit +``` +## Script Solution +Ours will look like this: + +```bash +# 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 + +# Create and edit our custom script +nano btcpay.cust-env.sh +``` + +In nano: +```bash +# modify these to your custom setup, for example adding options for cloudflare tunnel support +export BTCPAY_HOST="btcpay.EXAMPLE.com" +export NBITCOIN_NETWORK="mainnet" +export BTCPAYGEN_CRYPTO1="btc" +export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage-s" +export BTCPAYGEN_REVERSEPROXY="nginx" +export BTCPAYGEN_LIGHTNING="clightning" +export BTCPAY_ENABLE_SSH=true +``` +Save this by using CTRL+X, Y and Enter. + +Build the server: +```bash +# load the environment variables to your current session +source ./btcpay.cust-env.sh + +# build +. ./btcpay-setup.sh -i +``` + +## Updating the server + +So you logged out after building your very own BTCPay server implementation. +Things are going smoothly but now you find that you need to update the configuration to add support for a feature you hadn't originally implemented. +For this example, I'll add a cloudflare tunnel to the server. Keep in mind, you'll need to follow the [docs](./docs/cloudflare-tunnel.md) regarding the cloudflare website which I won't reproduce here. + +1. Follow the above steps to login as root and navigate to the `btcpayserver-docker` directory. + +2. Stop all btcpay related docker containers. You can use docker ps to make sure that these are the correct names for your containers. Modify accordingly. +```bash +docker stop nginx-gen btcpayserver_bitcoind nginx generated_btcpayserver_1 generated_nbxplorer_1 tor-gen generated_postgres_1 tor +``` + +3. Follow the [docs](./docs/cloudflare-tunnel.md) to create the cloudflare service on their website. Then, update the environment script file. +```bash +# edit the file +nano btcpay.cust-env.sh + +# Add these lines to the end of the file. Don't forget to modify the cloudflare tunnel token. +[[ "$REVERSEPROXY_DEFAULT_HOST" ]] && REVERSEPROXY_DEFAULT_HOST="$BTCPAY_HOST" +export CLOUDFLARE_TUNNEL_TOKEN="" +export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-cloudflared" +export BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;nginx-https" +``` +Again, saving the file using CTRL+X, Y and Enter. + +4. Rebuild the server. Fun fact: the bitcoin node is unaffected and you won't have to do another IBD :D + +Notice how the build process every time is just two lines with your variables saved safely in a file where you can view/modify them at will. +```bash +# load the environment variables to your current session +source ./btcpay.cust-env.sh + +# build +. ./btcpay-setup.sh -i +``` From a75ad1157b0c6f224c9c736160fa3c786b69d05a Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Mon, 15 Sep 2025 13:58:46 -0500 Subject: [PATCH 02/12] Update cloudflare-tunnel.md Fix ambiguity in Step 8 and add link to save-env-vars.md in two places. --- docs/cloudflare-tunnel.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/cloudflare-tunnel.md b/docs/cloudflare-tunnel.md index f41680e46..ab1d5b609 100644 --- a/docs/cloudflare-tunnel.md +++ b/docs/cloudflare-tunnel.md @@ -45,13 +45,16 @@ First, we are going to create the tunnel on Cloudflare. ![BTCPay Server Cloudflare Tunnel](./img/btcpayexposecloudflare5.jpg) -8. In the SSH section of your server, add Cloudflare tunnel by running the following script. (replace `` with what you copied in step `5.`, and also replace `` with the domain you entered in steps `7.`) +8. Log in to your server via SSH, login as root using `sudo su -` and change directory into `/path/to/btcpayserver-docker/`. Add Cloudflare tunnel by running the following script by pasting and running each line in order. (Replace `` with what you copied in step `5.`, and also replace `` with the domain you entered in step `7.`). + +Reminder: if you have logged out since originally building the server, you need to load ALL environment variables that your server is using before running `btcpay-setup.sh`. +See [here](./docs/save-env-vars.md) for more details. ```bash -BTCPAY_HOST="" +export BTCPAY_HOST="" [[ "$REVERSEPROXY_DEFAULT_HOST" ]] && REVERSEPROXY_DEFAULT_HOST="$BTCPAY_HOST" -CLOUDFLARE_TUNNEL_TOKEN="" -BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-cloudflared" -BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;nginx-https" +export CLOUDFLARE_TUNNEL_TOKEN="" +export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-cloudflared" +export BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;nginx-https" . btcpay-setup.sh -i ``` @@ -62,6 +65,10 @@ Now you should be able to access your server from the internet! (If you get an N In [cloudflare dashboard](https://dash.cloudflare.com), navigate to your websites, go to `Edge Certificates`, and check `Always Use HTTPS`. This will make sure that any request to your website uses HTTPS. ![](./img/Cloudflare-Always-Https.png) +## If using a script to save/load environment variables + +Add/update any environment variables you would export in step `8.` to the file you created using this [guide](./docs/save-env-vars.md) + ## Known error ### Error 503 From 47f8a6cecab32a298115af6cffa8d166d7ea8741 Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Mon, 15 Sep 2025 14:03:32 -0500 Subject: [PATCH 03/12] Update save-env-vars.md Added more detail to the Basic Way section --- docs/save-env-vars.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/save-env-vars.md b/docs/save-env-vars.md index 0dd1d5b34..49880b726 100644 --- a/docs/save-env-vars.md +++ b/docs/save-env-vars.md @@ -33,6 +33,33 @@ export BTCPAY_ENABLE_SSH=true exit ``` + +### Updating +SSH into the server, log in as root and navigate to the `btcpayserver-docker` folder. +```bash +# Login as root +sudo su - + +# Navigate to directory +cd BTCPayServer/btcpayserver-docker/ + +# export ALL environment variables fresh because they didn't stick from the first time. +export BTCPAY_HOST="btcpay.EXAMPLE.com" +export NBITCOIN_NETWORK="mainnet" +export BTCPAYGEN_CRYPTO1="btc" +export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage-s" +export BTCPAYGEN_REVERSEPROXY="nginx" +export BTCPAYGEN_LIGHTNING="clightning" +export BTCPAY_ENABLE_SSH=true +[[ "$REVERSEPROXY_DEFAULT_HOST" ]] && REVERSEPROXY_DEFAULT_HOST="$BTCPAY_HOST" +export CLOUDFLARE_TUNNEL_TOKEN="" +export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-cloudflared" +export BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;nginx-https" + +# build again +. ./btcpay-setup.sh -i +``` + ## Script Solution Ours will look like this: @@ -74,7 +101,7 @@ source ./btcpay.cust-env.sh . ./btcpay-setup.sh -i ``` -## Updating the server +### Updating with the script So you logged out after building your very own BTCPay server implementation. Things are going smoothly but now you find that you need to update the configuration to add support for a feature you hadn't originally implemented. From 1d5e296d5bcd8b88e33793ff545ec10175d0278b Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Tue, 16 Sep 2025 09:31:48 -0500 Subject: [PATCH 04/12] Update chatwoot.md Add link to save-env-vars.md. Fix typo. --- docs/chatwoot.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/chatwoot.md b/docs/chatwoot.md index 370634dec..f9435804b 100644 --- a/docs/chatwoot.md +++ b/docs/chatwoot.md @@ -16,6 +16,7 @@ cat >> Generated/chatwoot-config.env < Date: Tue, 16 Sep 2025 09:33:18 -0500 Subject: [PATCH 05/12] Update fireflyiii.md Add reference to save-env-vars.md --- docs/fireflyiii.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fireflyiii.md b/docs/fireflyiii.md index f1e8f4b91..e4c07b6b4 100644 --- a/docs/fireflyiii.md +++ b/docs/fireflyiii.md @@ -7,7 +7,7 @@ It can help you keep track of expenses, income, budgets and everything in betwee 1. Connect as root to your server 2. Configure a domain's DNS to point to your server ip. e.g. `firefly.yourserver.org` -3. Add fireflyiii as an option to your docker deployment +3. Add fireflyiii as an option to your docker deployment. *Note: if using a script to save your environment variables, save them to the script - [guide here](./docs/save-env-vars.md) ```bash BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-fireflyiii" From 1b5cb7ba5c77ae0471540bdeba005ccfb1234a45 Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Tue, 16 Sep 2025 09:37:33 -0500 Subject: [PATCH 06/12] Update joinmarket.md Add reference to save-env-vars.md --- docs/joinmarket.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/joinmarket.md b/docs/joinmarket.md index dbef14aaf..66c0bce6d 100644 --- a/docs/joinmarket.md +++ b/docs/joinmarket.md @@ -16,6 +16,7 @@ For hardcore bitcoiners only. BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-joinmarket" . btcpay-setup.sh -i ``` +Or add to script if using [this guide](./docs/save-env-vars.md). Then you need to setup your default joinmarket wallet: From fdacd095121f2bc2c51f06406f88e3de8ef7cfda Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Tue, 16 Sep 2025 09:39:22 -0500 Subject: [PATCH 07/12] Update lightning-terminal.md add reference to save-env-vars.md --- docs/lightning-terminal.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/lightning-terminal.md b/docs/lightning-terminal.md index b8ee3c5b5..bc1598b7b 100644 --- a/docs/lightning-terminal.md +++ b/docs/lightning-terminal.md @@ -16,6 +16,7 @@ export LIT_PASSWD="sUpErSeCuRe" export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-lightning-terminal" . btcpay-setup.sh -i ``` +If using [this guide](./docs/save-env-vars.md) to save your config to a script, remember to add the new options. Afterwards you should see Lightning Terminal appear as a service on the Server Settings > Services page in BTCPay Server. From b59f9b4019b7f1239477aa9fbbd1892d48fa473b Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Tue, 16 Sep 2025 09:40:36 -0500 Subject: [PATCH 08/12] Update ndlc.md --- docs/ndlc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/ndlc.md b/docs/ndlc.md index c1b07c207..e3cd4764c 100644 --- a/docs/ndlc.md +++ b/docs/ndlc.md @@ -39,6 +39,7 @@ You need to add ndlc's docker fragment to your install with: BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-ndlc" . btcpay-setup.sh -i ``` +If using [this guide](./docs/save-env-vars.md), remember to update script. You can then use `ndlc-cli.sh` to run use ndlc-cli, for example: From 29febd811d4692dd714eb3ae39e676a680da67f9 Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Tue, 16 Sep 2025 09:42:13 -0500 Subject: [PATCH 09/12] Update pihole.md add reference to save-env-vars.md --- docs/pihole.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/pihole.md b/docs/pihole.md index 2a500c07c..ea3024a52 100644 --- a/docs/pihole.md +++ b/docs/pihole.md @@ -16,6 +16,7 @@ Let's imagine the local IP of your BTCPay Server is `192.168.1.2`. BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-pihole" . btcpay-setup.sh -i ``` +If using [this guide](./docs/save-env-vars.md), remember to update script. 3. If your server has a firewall, make sure it allow incoming traffic to port `53 (UDP)`. 4. Configure your home router DHCP server to use `192.168.1.2` as primary DNS server. From c6ba4628de12056d227a15edfa9d5bf755b64f34 Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Tue, 16 Sep 2025 09:42:46 -0500 Subject: [PATCH 10/12] Update tallycoin-connect.md add reference to save-env-vars.md --- docs/tallycoin-connect.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tallycoin-connect.md b/docs/tallycoin-connect.md index 52da81b1a..d66fe9d1c 100644 --- a/docs/tallycoin-connect.md +++ b/docs/tallycoin-connect.md @@ -19,6 +19,7 @@ export TALLYCOIN_PASSWD_CLEARTEXT="sUpErSeCuRe" BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-tallycoin-connect" . btcpay-setup.sh -i ``` +If using [this guide](./docs/save-env-vars.md), remember to update script. Afterwards you should see Tallycoin Connect appear as a service on the Server Settings > Services page in BTCPay Server. From 1f9290f2c2e00ab07f85b77badc937696226afa7 Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Tue, 16 Sep 2025 09:48:29 -0500 Subject: [PATCH 11/12] Update cloudflare-tunnel.md simplified my original changes. --- docs/cloudflare-tunnel.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/cloudflare-tunnel.md b/docs/cloudflare-tunnel.md index ab1d5b609..5b8984fa0 100644 --- a/docs/cloudflare-tunnel.md +++ b/docs/cloudflare-tunnel.md @@ -45,10 +45,8 @@ First, we are going to create the tunnel on Cloudflare. ![BTCPay Server Cloudflare Tunnel](./img/btcpayexposecloudflare5.jpg) -8. Log in to your server via SSH, login as root using `sudo su -` and change directory into `/path/to/btcpayserver-docker/`. Add Cloudflare tunnel by running the following script by pasting and running each line in order. (Replace `` with what you copied in step `5.`, and also replace `` with the domain you entered in step `7.`). +8. Log in to your server via SSH, login as root and navigate to `path/to/btcpayserver-docker/`. Add Cloudflare tunnel by running the following script. (Replace `` with what you copied in step `5.`, and also replace `` with the domain you entered in step `7.`). If using [this guide](./docs/save-env-vars.md), remember to update script. -Reminder: if you have logged out since originally building the server, you need to load ALL environment variables that your server is using before running `btcpay-setup.sh`. -See [here](./docs/save-env-vars.md) for more details. ```bash export BTCPAY_HOST="" [[ "$REVERSEPROXY_DEFAULT_HOST" ]] && REVERSEPROXY_DEFAULT_HOST="$BTCPAY_HOST" @@ -65,10 +63,6 @@ Now you should be able to access your server from the internet! (If you get an N In [cloudflare dashboard](https://dash.cloudflare.com), navigate to your websites, go to `Edge Certificates`, and check `Always Use HTTPS`. This will make sure that any request to your website uses HTTPS. ![](./img/Cloudflare-Always-Https.png) -## If using a script to save/load environment variables - -Add/update any environment variables you would export in step `8.` to the file you created using this [guide](./docs/save-env-vars.md) - ## Known error ### Error 503 From 49db8fc776f5b6973410e377fd4d0978eeb3a2bb Mon Sep 17 00:00:00 2001 From: SeaSquared24 <84783719+SeaSquared24@users.noreply.github.com> Date: Tue, 16 Sep 2025 09:56:07 -0500 Subject: [PATCH 12/12] Update README.md add reference to save-env-vars.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 10ce1bc8d..b298e5044 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ Let's assume your domain is `btcpay.EXAMPLE.com`. The setup below assumes you want to support Bitcoin, Core Lightning (CLN), HTTPS automatically configured by Nginx. It also enables node pruning, which you can [modify](#generated-docker-compose) or ignore if you have enough disk space for a full node. Finally, your domain is `btcpay.EXAMPLE.com` should reflect your actual domain name. -[Environment variables](#environment-variables) can be tailored to your needs. Some variables require additional storage space. +[Environment variables](#environment-variables) can be tailored to your needs. Some variables require additional storage space. It may be useful to you to save your environment variables to a script, [details here](./docs/save-env-vars.md). ```bash # Login as root