first commit

docs/ARCHITECTURE.md

@@ -0,0 +1,46 @@
+# Architecture
+
+## Release path
+
+1. Debian cron runs once per hour.
+2. It refreshes the packaging repository containing this plugin/build logic.
+3. Independently, it fetches `APP_REPO_REF` from `https://git.linuxiarz.pl/gru/RustProxy` into `APP_WORKDIR`.
+4. It compares both current commits with the last successful build state.
+5. If either commit changed, Debian rsyncs the packaging tree and the RustProxy checkout separately to a FreeBSD 15.1 amd64 builder.
+6. FreeBSD reads the application version from the downloaded `Cargo.toml`, runs Cargo tests and a release build.
+7. The binary is injected into `opnsense-plugin/www/rustproxy/src/sbin/rust-proxy` inside a clean checkout of the official OPNsense plugins tree.
+8. `make package` creates `os-rustproxy-<version>_<revision>.pkg`.
+9. `pkg repo` creates a signed package repository.
+10. Debian downloads `dist/` and optionally publishes it over rsync/SSH.
+11. OPNsense consumes only the custom RustProxy package repository.
+
+The packaging repository deliberately contains no `app/` directory. This prevents stale application code from accidentally being packaged.
+
+## Upstream selection
+
+Default configuration:
+
+```text
+APP_REPO_URL=https://git.linuxiarz.pl/gru/RustProxy
+APP_REPO_REF=HEAD
+```
+
+`HEAD` follows the repository's default branch. To freeze releases, set `APP_REPO_REF` to a branch, tag or other fetchable ref. The exact commit used for each package is written to `dist/BUILD-INFO.txt`.
+
+## Why native FreeBSD for releases
+
+Rust can cross-compile to `x86_64-unknown-freebsd`, but a release also needs the target ABI and FreeBSD/OPNsense packaging behavior. A native FreeBSD builder makes both the Rust link step and `pkg` metadata/catalog generation match the target platform. The Docker/cross path is intended for fast developer validation only.
+
+## OPNsense plugin behavior
+
+The first UI version exposes only `general.enabled`.
+
+- Enabled: the service controller renders configuration and starts RustProxy through configd.
+- Disabled: the service controller stops RustProxy.
+- Boot: an OPNsense syshook regenerates configuration and starts the service only when enabled.
+
+RustProxy runs as the unprivileged `rustproxy` user. Its data is stored in `/var/db/rustproxy` and logs in `/var/log/rustproxy/rustproxy.log`.
+
+## Ports 80 and 443
+
+The MVP does not run RustProxy as root. Keep initial listeners above port 1023. If public 80/443 is required later, prefer an explicit PF redirect from 80/443 to high RustProxy listener ports instead of running the whole proxy as root.

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.