service/BTCpayserver.md

@@ -80,6 +80,70 @@ This will tail the logs of all the containers:
 
     docker-compose -f $BTCPAY_DOCKER_COMPOSE logs -f --tail=10
 
+## Manual backup and restore
+
+A manual backup/restore procedure might look like this:
+
+    systemctl stop btcpayserver
+    tar cfz backup.tgz /var/lib/docker/volumes/
+    systemctl start btcpayserver
+
+A restore, then, would look like this:
+
+    systemctl stop btcpayserver
+    mv /var/lib/docker/volumes/ /var/lib/docker/volumes.old # optional
+    tar -C / -x -f -z backup.tgz
+    systemctl start btcpayserver
+
+> If you're worried about the backup clobbering other files on restore
+> (for example you're not sure about the backup source or file
+> structure), this should restore only `volumes/` in the
+> `/var/lib/docker` directory:
+>
+>     systemctl stop btcpayserver
+>     mv /var/lib/docker/volumes/ /var/lib/docker/volumes.old # optional
+>     tar -C /var/lib/docker/ -x -f backup.tar.gz -z --strip-components=3
+>     systemctl start btcpayserver
+
+The `mv` step should be turned into a `rm -rf
+/var/lib/docker/volumes/` command if we are likely to run out of disk
+space on restore and we're confident in the backup's integrity.
+
+Note that the upstream backup procedure does *not* keep a copy of the
+blockchain, so this will be regenerated on startup. That, in turn, can
+take a *long* time (30 hours on last count). In that case, keeping a
+copy of the blockchain on restore might make sense, it is stored in:
+
+    /var/lib/docker/volumes/generated_bitcoin_datadir/_data/
+
+Finally, also note that if you *rename* the server (e.g. we moved from
+btcpay.torproject.net to btcpayserver.torproject.org in the past), you
+*also* need to perform a [rename procedure](https://docs.btcpayserver.org/Deployment/ChangeDomain/#how-to-change-the-domain-name-of-your-btcpay-server), which is basically:
+
+    /root/BTCPayServer/btcpayserver-docker/changedomain.sh btcpay.torproject.org
+
+### Faulty upstream procedure
+
+Upstream has a [backup procedure](https://docs.btcpayserver.org/Docker/#how-can-i-back-up-my-btcpay-server) but, oddly, [no restore
+procedure](https://github.com/btcpayserver/btcpayserver-docker/issues/629). It seems like, anyways, what the backup script does is:
+
+ 1. dump the database (in `$backup_volume/postgres.sql`)
+ 2. stops the server
+ 3. tar the Docker volumes (`/var/lib/docker/volumes/`) into a tar
+    file in the backup directory (`$backup_volume/backup.tar.gz`),
+    excluding the `generated_bitcoin_datadir` volume,
+    `generated_litecoin_datadir` **and** the `$backup_volume` (?!)
+ 4. start the server
+ 5. delete the database dump
+
+In the above, `$backup_volume` is
+`/var/lib/docker/volumes/backup_datadir/_data/`. And no, the
+`postgres.sql` database dump is not in the backups. I filed [upstream
+issue 628](https://github.com/btcpayserver/btcpayserver-docker/issues/628) about this as well.
+
+We do not recommend using the upstream backup procedures in their
+current state.
+
 ## Pager playbook
 
 When you're lost, look at the variables in
@@ -142,6 +206,12 @@ by following our [install procedures](#installation) and then hooking up the
 hardware wallet to the server. In practice, that is undocumented and
 hasn't been tested.
 
+Normally, you should be able to restore parts (or the entirety) of
+this service using the normal [backup procedures](howto/backup). But those
+backups may be inconsistent. If an emergency server migration is
+possible (ie. the old server is still online), follow the [manual
+backup and restore procedure](#manual-backup-and-restore).
+
 # Reference
 
 ## Installation
@@ -513,54 +583,8 @@ backup `/var/lib/docker` as is. Yes, including the blockchain crap,
 because that actually takes a long time to recover. Consistency might
 be a problem. Sorry.
 
-A manual backup/restore procedure might look like this:
-
-    systemctl stop btcpayserver
-    tar cfz backup.tgz /var/lib/docker/volumes/
-    systemctl start btcpayserver
-
-A restore, then, would look like this:
-
-    systemctl stop btcpayserver
-    mv /var/lib/docker/volumes/ /var/lib/docker/volumes.old # optional
-    tar -C / -x -f -z backup.tgz
-    systemctl start btcpayserver
-
-The `mv` step should be turned into a `rm -rf
-/var/lib/docker/volumes/` command if we are likely to run out of disk
-space on restore and we're confident in the backup's integrity.
-
-If you're worried about the backup clobbering other files on restore
-(for example you're not sure about the backup source or file
-structure), this should restore only `volumes/` in the
-`/var/lib/docker` directory:
-
-    systemctl stop btcpayserver
-    mv /var/lib/docker/volumes/ /var/lib/docker/volumes.old # optional
-    tar -C /var/lib/docker/ -x -f backup.tar.gz -z --strip-components=3
-    systemctl start btcpayserver
-
-### Faulty upstream procedure
-
-Upstream has a [backup procedure](https://docs.btcpayserver.org/Docker/#how-can-i-back-up-my-btcpay-server) but, oddly, [no restore
-procedure](https://github.com/btcpayserver/btcpayserver-docker/issues/629). It seems like, anyways, what the backup script does is:
-
- 1. dump the database (in `$backup_volume/postgres.sql`)
- 2. stops the server
- 3. tar the Docker volumes (`/var/lib/docker/volumes/`) into a tar
-    file in the backup directory (`$backup_volume/backup.tar.gz`),
-    excluding the `generated_bitcoin_datadir` volume,
-    `generated_litecoin_datadir` **and** the `$backup_volume` (?!)
- 4. start the server
- 5. delete the database dump
-
-In the above, `$backup_volume` is
-`/var/lib/docker/volumes/backup_datadir/_data/`. And no, the
-`postgres.sql` database dump is not in the backups. I filed [upstream
-issue 628](https://github.com/btcpayserver/btcpayserver-docker/issues/628) about this as well.
-
-We do not recommend using the upstream backup procedures in their
-current state.
+Full backup restore procedures are visible in the [backup and restore
+section](#manual-backup-and-restore).
 
 ## Other documentation