add borg recovery details

RECOVERY.md

@@ -0,0 +1,97 @@
+# Forgejo Repository Recovery
+
+This is the minimal recovery path for getting source code back from the
+BorgBase backup. It does not rebuild the full server; it extracts Forgejo's
+bare Git repositories so they can be cloned locally.
+
+## Requirements
+
+- BorgBase repo URL:
+  `ssh://n5lniyfd@n5lniyfd.repo.borgbase.com/./repo`
+- Decrypted Borg SSH private key from the flash drive
+- Borg repository passphrase from the flash drive
+- A machine with `borg`, `git`, and `ssh`
+
+This only recovers repositories that were pushed to Forgejo before the selected
+Borg backup ran.
+
+## Recovery
+
+Install the needed tools. On NixOS or another machine with Nix:
+
+```sh
+nix-shell -p borgbackup git openssh
+```
+
+Prepare a working directory and copy in the Borg SSH key:
+
+```sh
+mkdir -p ~/borg-recovery
+cp /path/to/flash/borg-private-key ~/borg-recovery/borg-private-key
+chmod 600 ~/borg-recovery/borg-private-key
+```
+
+Set the Borg connection environment:
+
+```sh
+export BORG_REPO='ssh://n5lniyfd@n5lniyfd.repo.borgbase.com/./repo'
+export BORG_RSH='ssh -i ~/borg-recovery/borg-private-key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new'
+```
+
+Read the Borg passphrase without showing it on screen:
+
+```sh
+read -rsp 'Borg passphrase: ' BORG_PASSPHRASE
+export BORG_PASSPHRASE
+echo
+```
+
+List available archives:
+
+```sh
+borg list
+```
+
+Choose an archive name from the list, then extract only Forgejo's Git
+repositories:
+
+```sh
+mkdir -p ~/borg-recovery/extract
+cd ~/borg-recovery/extract
+
+borg extract ::ARCHIVE_NAME var/lib/forgejo/repositories
+```
+
+Find the extracted bare repositories:
+
+```sh
+find ~/borg-recovery/extract/var/lib/forgejo/repositories -maxdepth 3 -name '*.git'
+```
+
+Clone the repository you need:
+
+```sh
+git clone ~/borg-recovery/extract/var/lib/forgejo/repositories/OWNER/REPO.git
+```
+
+Example:
+
+```sh
+git clone ~/borg-recovery/extract/var/lib/forgejo/repositories/yisroel/home-server-config.git
+```
+
+## About the Passphrase Command
+
+This command:
+
+```sh
+read -rsp 'Borg passphrase: ' BORG_PASSPHRASE
+```
+
+reads the passphrase into the `BORG_PASSPHRASE` shell variable.
+
+- `-r` reads the text literally.
+- `-s` hides what you type.
+- `-p` shows the prompt.
+
+Then `export BORG_PASSPHRASE` makes the variable available to `borg`.