v0.28.1

docs/INSTALL.md

@@ -1,4 +1,4 @@
-# Installing and updating RustProxy 0.28.0
+# Installing and updating RustProxy 0.28.1
 
 The scripts prepare a Linux/systemd installation. This source archive is **not a
 verified production build**: Rust/Cargo, real CA operations, live systemd startup
@@ -200,8 +200,36 @@ The provider script is embedded in the RustProxy binary; this command is diagnos
 
 If another service already owns a certificate through the system Certbot, keep that lineage
 outside RustProxy's managed ACME profiles and create/use a **manual** RustProxy certificate id.
-A Certbot deploy hook can publish every successful renewal to all vhosts that already select
-that id:
+
+The preferred 0.28.1 workflow is to select **Existing server files / external paths** and then
+**External files (absolute paths)** in the Certificates panel. For example:
+
+```text
+Certificate: /etc/letsencrypt/live/example.com/fullchain.pem
+Private key: /etc/letsencrypt/live/example.com/privkey.pem
+```
+
+RustProxy does not copy these files into its data directory. On every targeted reload it resolves
+Certbot's `live/` symlinks again, validates the new certificate/key pair and atomically publishes a
+new public TLS snapshot. A renewal wrapper can therefore call:
+
+```bash
+curl --fail --show-error -X POST \
+  -H 'Authorization: Bearer TOKEN' \
+  -H 'X-RustProxy-Certificate-Key: certbot-main' \
+  -H 'Content-Type: application/json' \
+  --data '{}' \
+  https://proxy-admin.example/api/certificates/shared-cert/reload
+```
+
+The `rustproxy` service identity must be able to traverse the parent directories and read both
+files. An external private key may be `0600` when owned by that identity or `0640` with a
+restricted group readable by RustProxy; world access, group write and executable bits are
+rejected. These external files are not included in a RustProxy backup.
+
+If you do not want the RustProxy service to read `/etc/letsencrypt`, keep the previous copy/deploy
+workflow instead. A Certbot deploy hook can publish every successful renewal into RustProxy's
+managed certificate directory:
 
 ```bash
 /opt/rustproxy/current/rust-proxy --data-dir /var/lib/rustproxy tls deploy --id shared-cert \
@@ -209,10 +237,12 @@ that id:
   --key /etc/letsencrypt/live/example/privkey.pem
 ```
 
-The command reads the Certbot files locally and sends them to the authenticated loopback `POST /api/certificates/deploy` endpoint. The running RustProxy service writes the private generation with its own filesystem identity and hot-publishes it for new public TLS/H2/H3 handshakes. No per-vhost edit is needed. If another
-local process instead replaces the exact files already referenced by RustProxy, run
-`/opt/rustproxy/current/rust-proxy --data-dir /var/lib/rustproxy tls reload` (or authenticated `POST /api/certificates/reload`) afterward. If the replacement belongs to one configured manual certificate ID, automation may instead call `POST /api/certificates/{certificate_id}/reload`; the same endpoint accepts a scoped Certificate API Key ID + Bearer token and does not change the configuration revision.
-Administration TLS is startup-fixed and may still require a service restart.
+The deploy command reads the Certbot files locally and sends them to the authenticated loopback
+`POST /api/certificates/deploy` endpoint. The running RustProxy service writes a private managed
+generation and hot-publishes it for new public TLS/H2/H3 handshakes. Do not use `deploy` for a
+certificate ID configured with external absolute paths; renew those files in place and call the
+targeted reload endpoint instead. Administration TLS is startup-fixed and may still require a
+service restart.
 
 Optional environment overrides go in a root-owned `/etc/rustproxy/environment`
 (mode 0600); create the directory when needed. Restart after changing service