From 6d3909c334ce869fba3f39959f5f3d9ebcfc325a Mon Sep 17 00:00:00 2001
From: "Foluso ADEBISI (DevBox Aux)" <adebisi-fa@live.com>
Date: Fri, 2 Oct 2026 09:53:35 +0100
Subject: [PATCH] docs(fpagent): document the one-line installer and its key

---
 .env.example | 12 +++++++++---
 README.md    | 37 +++++++++++++++++++++++++++++--------
 2 files changed, 38 insertions(+), 11 deletions(-)

diff --git a/.env.example b/.env.example
index ca111dd..a81abd9 100644
--- a/.env.example
+++ b/.env.example
@@ -1,6 +1,6 @@
-# Image Cropper service credentials — the ONLY environment variables this app
-# uses. Everything else (URLs, port, domain catalog) is hardcoded in source.
-# Without these the rest of the app works and /cropper answers 503.
+# Image Cropper service credentials. Everything else (URLs, port, domain
+# catalog) is hardcoded in source. Without these the rest of the app works and
+# /cropper answers 503.
 #
 # This repository uses dotenvx-encrypted env files (.env, .env.production);
 # the private keys live in .env.keys (gitignored). To set up or change a value:
@@ -16,3 +16,9 @@ AZURE_STORAGE_CONNECTION_STRING=
 NODERED_HTTP_USERNAME=
 NODERED_HTTP_PASSWORD=
 CARVEKIT_API_KEY=
+
+# Token the server uses to read the private fpagent releases from the forge
+# (https://sources.yrka.app). It stays server-side: /fpagent/releases/* proxies
+# the bundles for the public installer at /fpagent/install.sh. Without it the
+# installer answers 503.
+GITEA_RELEASE_INSTALL_KEY=
diff --git a/README.md b/README.md
index fb323ae..25d0ffa 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,8 @@ tools/
 ├── cropper.js              # /cropper router (queue, review, save) — injectable clients
 ├── public/
 │   ├── index.html          # landing page shell (tiles injected per session)
+│   ├── fpagent/
+│   │   └── install.sh      # public /fpagent/install.sh (proxies private releases)
 │   └── assets/
 │       ├── style.css       # shared Carbon-styled layout + g100 theme
 │       ├── help.html       # /help docs page
@@ -119,9 +121,10 @@ record, crop the photo, optionally **Clean background**, then accept or reject
 with reasons. Reads may use the cached `crop_image` verdict; saving re-verifies
 live and uploads through the queue.
 
-Its service credentials are the **only** environment variables this app uses.
-They live in dotenvx-encrypted files at the repository root — `.env` for
-development, `.env.production` for deployment:
+Its service credentials live in dotenvx-encrypted files at the repository root
+— `.env` for development, `.env.production` for deployment. The fpagent
+installer key is read from the same files (see
+[Installing the agent](#installing-the-agent)):
 
 ```sh
 MINIO_ACCESS_KEY=…            MINIO_SECRET_KEY=…
@@ -149,13 +152,31 @@ The `/fingerprint` wizard walks the operator through:
    travel with every `fprint-enroll` to fpagent.
 3. **Save** — both templates are posted to a2loft with a fresh OTP.
 
+### Installing the agent
+
+`/fpagent/install.sh` is a public installer (also served for `curl | bash`). It
+fetches the newest bundle from the private
+[`fingerprint-agent`](https://sources.yrka.app/YOUreka/fingerprint-agent/releases)
+forge, verifies its sha256, then runs the bundle's own installer, which handles
+libfprint, the udev rule, `plugdev` and the systemd service. On a field laptop:
+
+```sh
+curl -fsSL https://tools.yrka.app/fpagent/install.sh | bash -s -- --enable-service
+curl -fsSL https://tools.yrka.app/fpagent/install.sh | bash -s -- --check   # report only
+```
+
+The forge is private, so the operator's laptop needs no credentials: the app
+reads the release with `GITEA_RELEASE_INSTALL_KEY` and proxies it through
+`/fpagent/releases/*`. Without that key the installer answers `503`.
+
 ## Configuration
 
-Everything except the cropper credentials is hardcoded in `tools/server.js` by
-design — port `4173`, portal `https://portal.yrka.app`, PocketBase
-`https://pb.itcass.net`, a2loft `https://apis.a2loft.net`, agent
-`http://127.0.0.1:9000`, and the domain catalog. Change them there; there are no
-other environment variables or config files.
+Everything except the credentials is hardcoded in `tools/server.js` by design —
+port `4173`, portal `https://portal.yrka.app`, PocketBase `https://pb.itcass.net`,
+a2loft `https://apis.a2loft.net`, agent `http://127.0.0.1:9000`, forge
+`https://sources.yrka.app` and the domain catalog. Change them there. The only
+environment variables are the cropper credentials and the fpagent installer key
+`GITEA_RELEASE_INSTALL_KEY` above.
 
 ## Deployment