first commit

docs/FIRST_RUN.md

@@ -0,0 +1,109 @@
+# First run
+
+## 1. Push this packaging repository
+
+Create a repository for the generated OPNsense plugin/build files and push this tree there. RustProxy itself must not be copied into this repository; it will be fetched dynamically from:
+
+```text
+https://git.linuxiarz.pl/gru/RustProxy
+```
+
+After pushing, set that new repository address as `PACKAGING_REPO_URL` in the Debian configuration.
+
+## 2. Prepare the FreeBSD release builder
+
+Use FreeBSD 15.1 amd64.
+
+```sh
+sudo sh builder/freebsd/bootstrap.sh builder
+sudo -u builder sh builder/freebsd/create-repo-key.sh
+```
+
+The bootstrap creates a non-root `builder` account and gives it `/usr/local/rustproxy-build`.
+
+## 3. Prepare Debian
+
+From a checkout of this packaging repository:
+
+```sh
+sudo bash builder/debian/install.sh
+sudo editor /etc/rustproxy-opnsense-builder.env
+```
+
+At minimum configure:
+
+```text
+PACKAGING_REPO_URL=<URL of this new packaging repository>
+PACKAGING_REPO_REF=main
+
+APP_REPO_URL=https://git.linuxiarz.pl/gru/RustProxy
+APP_REPO_REF=HEAD
+
+FREEBSD_HOST=<FreeBSD builder>
+FREEBSD_USER=builder
+FREEBSD_REMOTE_DIR=/usr/local/rustproxy-build/project
+```
+
+`APP_REPO_REF=HEAD` means "build the current default branch". If you want controlled releases, change it to a specific branch or tag.
+
+Run the first cycle manually:
+
+```sh
+sudo /usr/local/sbin/rustproxy-opnsense-hourly
+```
+
+Cron runs at minute 17 of every hour. Each run fetches the RustProxy upstream. A new build starts when either the upstream RustProxy commit or this packaging repository commit changed. A failed build does not update `last-successful-build`, so it is retried on the next run.
+
+## 4. Build state
+
+Debian stores checkouts separately:
+
+```text
+/srv/rustproxy-opnsense/packaging/       # this repository
+/srv/rustproxy-opnsense/source/RustProxy # dynamically fetched app
+/var/lib/rustproxy-opnsense-builder/     # lock + last successful commit pair
+```
+
+The FreeBSD build machine receives the two trees separately. Its temporary `$FREEBSD_REMOTE_DIR/app/` always comes from the upstream checkout, never from the packaging repository.
+
+## 5. Publish `dist/`
+
+Set `PUBLISH_TARGET`. The published layout is similar to:
+
+```text
+/rustproxy/
+  BUILD-INFO.txt
+  SHA256
+  rustproxy-repo.pub
+  repository/
+    26.7/
+      amd64/
+        os-rustproxy-<Cargo-version>_<revision>.pkg
+        meta.conf
+        data.pkg
+        packagesite.pkg
+```
+
+`BUILD-INFO.txt` contains the RustProxy source URL, ref and exact commit used to create the package.
+
+## 6. Install on OPNsense
+
+Copy `rustproxy-repo.pub` to the firewall and run:
+
+```sh
+sh deploy/opnsense/install-repo.sh \
+  https://packages.example.net/rustproxy/repository/26.7/amd64 \
+  /tmp/rustproxy-repo.pub
+```
+
+Then open `Services -> RustProxy`, enable it and click Apply.
+
+## 7. Update
+
+Publishing a new package does not automatically upgrade production firewalls. Run:
+
+```sh
+sh deploy/opnsense/update.sh
+```
+
+`AUTO_DEPLOY_HOSTS` exists only for explicitly listed test firewalls and is empty by default.