From 3c04c6a68cf687a4c51f48e81612666f01281f7e Mon Sep 17 00:00:00 2001 From: Andreas Tasch Date: Fri, 16 Dec 2022 11:36:37 +0100 Subject: [PATCH 1/4] Adding steps for a server migration. --- docs/backup-restore.md | 57 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/backup-restore.md b/docs/backup-restore.md index f87793a00..190f14408 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -175,3 +175,60 @@ Always make sure your backup strategy is tested and fits your needs. No one solution fits all, and we tried to cover the basic cases. For the latest updates, always feel free to ask on the BTCPay Server community channels. ::: + +## How to migrate to a new server? + +The necessary steps always depend on your setup and infrastructure but as a rough guideline the following steps and considerations will get you through the process. + +:::warning +If you have Lightning Network (LN) channels open on your internal node, you need to make sure to **not** restore any old channel state, otherwise your are at the risk of loosing funds. Therefore it is important to shut down BTCPay on the old server immediately after the backup has finished as outlined below. +::: + +**Definitions:** +NEW = steps to be done on the NEW server +OLD = steps to be done on the OLD server + + +### Preparation + +#### Temporarily reduce the TTL of your domain: +Depending on the TTL (time-to-live) of your DNS entries (A-Record) for you BTCPay Server domains/subdomains it makes sense to reduce the TTL a day or a few hours before you want to start the migration. In case anything goes wrong you can quickly switch between new and old server IP addresses. You should set the TTL for the domain/subdomain to some shorter timewindow eg. 600 seconds (10 minutes) or if possible 300 seconds (5 mins). You can do this in at your domain registrar control center. + +#### Environment variables: +write down the environment variables you need for the setup on the new server as written in the [Docker installation guide](/Docker/#full-installation-for-technical-users). + +```bash +echo $BTCPAY_HOST +echo $NBITCOIN_NETWORK +echo $BTCPAYGEN_CRYPTO1 +echo $BTCPAYGEN_ADDITIONAL_FRAGMENTS +echo $BTCPAYGEN_REVERSEPROXY +echo $BTCPAYGEN_LIGHTNING +echo $BTCPAY_ENABLE_SSH +``` + +:::tip +If you have custom modifications or additional altcoins then do not forget export those environment variables too. +::: + + +#### Prepare the NEW server: + +Install the operating system on the new server/VPS without installing BTCPay, yet. + + +### Migration steps + +#### On the OLD server: +- [make the backup](#how-does-the-backup-work) +- stop all containers by running `./btcpay-stop.sh` (this ensures no outdated LN channel state gets restored on the new server) +- copy the backup archive to new server + +#### At the domain registrar: +Change the DNS A-Record of your domains/subdomains to the NEW server IP address and wait 5-10 mins (depending on the TTL) + +#### On the NEW server: +- install BTCPay according to [our Docker installation guide](/Docker/#full-installation-for-technical-users) but with the same environment variable values you wrote down in the preparation steps above +- wait until the installation finished (takes a few minutes) and check if you can access the btcpay interface, you will see that the node is still synching which is fine +- run the [restore process](#how-to-restore) (you can do this even if node not fully synced yet, it will continue after the restore is finished) +- if everything works on the new server you can shutdown and wipe the old server From 58a48e37305fcb47843d0af7f3732d00dce20828 Mon Sep 17 00:00:00 2001 From: Andreas Tasch Date: Fri, 16 Dec 2022 11:38:37 +0100 Subject: [PATCH 2/4] Fix wording. --- docs/backup-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backup-restore.md b/docs/backup-restore.md index 190f14408..1cad901a3 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -208,7 +208,7 @@ echo $BTCPAY_ENABLE_SSH ``` :::tip -If you have custom modifications or additional altcoins then do not forget export those environment variables too. +If you have custom modifications or additional altcoins then do not forget write down those environment variables too. ::: From 4f744b763466e0bc8a06a9d2d8c7174248dc803a Mon Sep 17 00:00:00 2001 From: Andreas Tasch Date: Fri, 16 Dec 2022 11:41:45 +0100 Subject: [PATCH 3/4] Remove definitions as they are redundant. --- docs/backup-restore.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/backup-restore.md b/docs/backup-restore.md index 1cad901a3..41ee401ab 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -184,10 +184,6 @@ The necessary steps always depend on your setup and infrastructure but as a roug If you have Lightning Network (LN) channels open on your internal node, you need to make sure to **not** restore any old channel state, otherwise your are at the risk of loosing funds. Therefore it is important to shut down BTCPay on the old server immediately after the backup has finished as outlined below. ::: -**Definitions:** -NEW = steps to be done on the NEW server -OLD = steps to be done on the OLD server - ### Preparation From 43b3e1584c6182a92b649e0f6e6deddfd7d6c9b1 Mon Sep 17 00:00:00 2001 From: Andreas Tasch Date: Fri, 16 Dec 2022 23:12:02 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: d11n --- docs/backup-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backup-restore.md b/docs/backup-restore.md index 41ee401ab..81be776f1 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -204,7 +204,7 @@ echo $BTCPAY_ENABLE_SSH ``` :::tip -If you have custom modifications or additional altcoins then do not forget write down those environment variables too. +If you have custom modifications or additional altcoins then do not forget to write down those environment variables too. :::