# 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.