phoenixd upgrade

02_vps_core_services_setup.md

@@ -198,9 +198,58 @@ Checklist:
 - [ ] SSH cloning works after setting up your SSH pub key
 
 
+## Phoenixd
+
+phoenixd is the server version of the Phoenix wallet: a self-custodial Lightning node that leans on the ACINQ node for liquidity and channel management. It is the Lightning backend that LNBits talks to, so deploy it first.
+
+It is not exposed to the internet. Its HTTP API is bound to `127.0.0.1` and only local consumers (LNBits, running on the same host) use it. There is no subdomain and no Caddy config for it.
+
+### Deploy
+
+* Review `ansible/services/phoenixd/phoenixd_vars.yml`. The things worth a look:
+    * `phoenixd_version`: pinned release tag.
+    * `phoenixd_auto_liquidity`: how much inbound liquidity phoenixd buys when it needs some (`off`, `2m`, `5m`, `10m`). This costs sats, it is not free.
+    * `phoenixd_http_bind_port`: the loopback API port LNBits will point at.
+* No new secrets are needed: phoenixd generates its own API password on first start.
+* Run the deployment playbook: `ansible-playbook -i inventory.ini services/phoenixd/deploy_phoenixd_playbook.yml`.
+* The playbook will:
+    * Install `phoenixd` and `phoenix-cli` into `/usr/local/bin`
+    * Create the `phoenix` system user and a `0700` data dir at `/opt/phoenixd/.phoenix`
+    * Create and start the `phoenixd` systemd service
+    * Create a health check timer that runs `phoenix-cli getinfo` every minute
+    * Register a push monitor named `Phoenixd` in Uptime Kuma under the `services` group
+
+### Back up the seed
+
+**Do this immediately after the first deploy.** The seed is the only thing that recovers the funds.
+
+* Run the backup playbook: `ansible-playbook -i inventory.ini services/phoenixd/setup_backup_phoenixd_to_lapy.yml`.
+* This gpg encrypts `seed.dat` and `phoenix.conf` to Lapy daily and keeps 14 days. It does not stop the node and it does not back up the channel database on purpose: phoenixd keeps channel state with its peer, and restoring a stale channel db to a live node can force close channels and cost you a penalty.
+* Also write the 12 words down offline, once: `sudo cat /opt/phoenixd/.phoenix/seed.dat`.
+
+### Operate
+
+* Status: `sudo systemctl status phoenixd`, logs: `sudo journalctl -u phoenixd -f`.
+* CLI: `sudo PHOENIX_DATADIR=/opt/phoenixd/.phoenix phoenix-cli getinfo` (also `getbalance`, `listchannels`, `createinvoice`). If you changed `phoenixd_http_bind_port`, add `--http-bind-port <port>` before the subcommand.
+* API password, needed to wire anything up to the node: `sudo grep '^http-password=' /opt/phoenixd/.phoenix/phoenix.conf`.
+
+### Restoring on a fresh host
+
+* Deploy phoenixd but stop the service before it generates a new seed, or just drop the file in before the first run:
+    * `sudo mkdir -p /opt/phoenixd/.phoenix`
+    * `echo "your twelve words here" | sudo tee /opt/phoenixd/.phoenix/seed.dat`
+    * `sudo chown -R phoenix:phoenix /opt/phoenixd/.phoenix && sudo chmod 600 /opt/phoenixd/.phoenix/seed.dat`
+* Then run the deployment playbook. Never run two nodes on the same seed at once.
+
+Checklist:
+- [ ] `phoenix-cli getinfo` returns a node id
+- [ ] The `Phoenixd` monitor in Uptime Kuma is green
+- [ ] The seed is backed up to Lapy *and* written down offline
+
+
 ## LNBits
 
-LNBits is a Lightning Network wallet and accounts system.
+LNBits is a Lightning Network wallet and accounts system. It uses the phoenixd node deployed above as its Lightning backend.
 
 ### Deploy
 
@@ -214,6 +263,7 @@ LNBits is a Lightning Network wallet and accounts system.
 * From that point on, you can configure through the Web UI.
 * Some advice around specifics of LNbits:
     * The default setup uses a FakeWallet backend for testing. Configure a real Lightning backend as needed by modifying the `.env` file located or using the superuser UI.
+    * To use the phoenixd node deployed above, set the backend to `PhoenixdWallet` with endpoint `http://127.0.0.1:9740` and the API password from `/opt/phoenixd/.phoenix/phoenix.conf`. The deployment playbook does not do this for you, since flipping the wallet backend on a live instance is not something to do behind your back.
     * For security, disable the new users registration.
 
 ### Set up backups to Lapy