491 lines
28 KiB
Markdown
491 lines
28 KiB
Markdown
# RustProxy unified package builder
|
||
|
||
Wydanie wdrożeniowe (odchudzone): zawiera panel, konfigurację Nginx oraz wszystkie skrypty budowania Linux, OPNsense i FreeBSD. Nie zawiera pustych szkieletów projektów; dołączono lekkie testy offline dla pakowania SUSE. Istniejące katalogi `data/`, `gpg/` i plik `.env` pozostają nienaruszone podczas rozpakowywania.
|
||
|
||
Jeden kontener buildera buduje z jednego commita RustProxy:
|
||
|
||
- Linux x86_64: DEB + podpisane repo APT (`rustproxy` **oraz osobny** `rustproxy-docker-agent`),
|
||
- Linux x86_64: RPM + podpisane repo DNF/YUM (`rustproxy` **oraz osobny** `rustproxy-docker-agent`),
|
||
- **SUSE / openSUSE / openSUSE Leap x86_64**: oddzielne paczki RPM dostosowane do `zypper`, podpisane repo `suse/x86_64` (`rustproxy` i `rustproxy-docker-agent`),
|
||
- FreeBSD x86_64: cross-build bez VM FreeBSD,
|
||
- OPNsense: `os-rustproxy-<version>_<revision>.pkg` + statyczne repo `pkg`,
|
||
- **natywne FreeBSD** (domyślnie włączone): `rustproxy-<version>_<revision>.pkg` + osobny katalog repo `pkg` pod `/freebsd/` (bez zależności OPNsense).
|
||
|
||
**Agent Docker jest pakowany wyłącznie na Linux (DEB/RPM); brak paczki FreeBSD pkg dla agenta.** Nie ma Docker-in-Docker, SCP ani osobnego watchera repo OPNsense. FreeBSD sysroot, clang/lld i Rust target są częścią głównego obrazu buildera. OPNsense dostaje osobny publiczny adres. Gałąź Linux, gałąź OPNsense i gałąź natywnego FreeBSD są budowane oraz publikowane niezależnie, więc błąd testów Linux nie blokuje pakietu FreeBSD.
|
||
|
||
## Panel repozytorium (RustProxy Package Registry)
|
||
|
||
The dashboard interface defaults to **English (`en-GB`)**, including its dates, navigation, notifications, and installation instructions. The **Docker discovery agent** installation card is shown only for **Linux (DEB/RPM, including SUSE/Zypper)**, never for OPNsense or native FreeBSD. Package listings/API also omit any stray agent PKG files for the FreeBSD channels.
|
||
|
||
Strony startowe repozytoriów (Linux DNF/APT, SUSE, OPNsense, FreeBSD) działają jako **lekka aplikacja Python** (`dashboard/`) za istniejącym Nginx. Wygląd nawiązuje do panelu RustProxy 0.34.6 (ciemny, jasny i kremowy motyw). **APT, RPM i pkg są nadal obsługiwane bezpośrednio przez Nginx**, więc mechanizm aktualizacji paczek, ścieżki plików, podpisy GPG i atomowe przełączanie `current` nie zmieniają się.
|
||
|
||
Panel udostępnia:
|
||
|
||
- **Przegląd**: najnowsza wersja, czas buildu, commit, stan Linux / SUSE / OPNsense / FreeBSD, statystyki i ostatnie paczki.
|
||
- **Paczki i wersje**: pełny katalog z nazwą, wersją, architekturą, datą, rozmiarem i linkiem pobrania; wyszukiwanie, sortowanie oraz filtry formatów/kanałów.
|
||
- **Instalacja**: aktualne polecenia dla APT, DNF, Zypper, OPNsense i natywnego FreeBSD oraz przyciski kopiowania.
|
||
- **Repozytoria**: linki do metadanych, katalogów i klucza GPG. Automatyczne odświeżanie co **60 sekund** oraz ręczne odświeżenie.
|
||
|
||
Adresy paneli (bez zmian domen i portów):
|
||
|
||
```text
|
||
REPOSITORY_URL/ Linux DEB + RPM (DNF) + SUSE RPM (Zypper)
|
||
REPOSITORY_URL/suse/x86_64/ podpisane RPM i metadane dla SUSE/openSUSE
|
||
OPNSENSE_REPOSITORY_URL/ OPNsense pkg
|
||
OPNSENSE_REPOSITORY_URL/freebsd/ Native FreeBSD pkg
|
||
```
|
||
|
||
Publiczne API, np. `https://twoje-repo.example/api/v1/packages`, zwraca JSON z `builds`, `packages` i `summary`. API jest dostępne na obu hostach. Panel nie zapisuje nic w repo; odczytuje wyłącznie opublikowany snapshot `data/repository/current`. Kontener Python nie publikuje portu hosta i ma dostęp **tylko do odczytu**.
|
||
|
||
Nowe buildy zapisują `built_at` w `LINUX-BUILD-INFO.txt` oraz `BUILD-INFO.txt` dla OPNsense/FreeBSD (UTC, ISO 8601). **Dla wydań sprzed tej zmiany** panel pokazuje czas modyfikacji pliku, oznaczony w podpowiedzi; nie twierdzi, że to potwierdzony czas buildu. Przełączanie wersji działa automatycznie i nie wymaga ponownego uruchamiania panelu.
|
||
|
||
Uruchomienie po aktualizacji projektu:
|
||
|
||
```bash
|
||
./start.sh
|
||
# lub ręcznie (przy ustawionym .env):
|
||
docker compose --env-file .env build repository-dashboard
|
||
docker compose --env-file .env up -d repository-dashboard repository-http
|
||
|
||
# API i zdrowie nginx
|
||
curl -fsS http://127.0.0.1:18765/api/v1/packages
|
||
curl -fsS http://127.0.0.1:18765/healthz
|
||
|
||
```
|
||
|
||
Panel zależy wyłącznie od biblioteki standardowej Pythona, bez dodatkowych pakietów pip. Jeżeli nie ma jeszcze buildów, pokaże komunikat **brak paczek**, a nie fikcyjne wersje.
|
||
|
||
## Szybki start
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env
|
||
./start.sh
|
||
```
|
||
|
||
Minimalnie ustaw:
|
||
|
||
```env
|
||
SOURCE_REPO=https://git.linuxiarz.pl/gru/RustProxy.git
|
||
REPOSITORY_URL=http://192.168.1.100
|
||
OPNSENSE_REPOSITORY_URL=https://opn-rustproxy.linuxiarz.pl
|
||
```
|
||
|
||
Dla `http://` bez portu `start.sh` dopisze domyślny port. Dla `https://` zakładany jest zewnętrzny reverse proxy/TLS.
|
||
|
||
Domyślne lokalne porty:
|
||
|
||
```text
|
||
APT/RPM/Zypper: 18765 -> nginx :8080
|
||
OPNsense: 18766 -> nginx :8081
|
||
```
|
||
|
||
Przykładowo reverse proxy może kierować:
|
||
|
||
```text
|
||
packages.example.net -> http://builder:18765
|
||
opn-rustproxy.linuxiarz.pl -> http://builder:18766
|
||
```
|
||
|
||
## Pipeline
|
||
|
||
```text
|
||
Git RustProxy
|
||
|
|
||
wspólny checkout
|
||
/ \
|
||
/ \
|
||
Linux branch FreeBSD cross-build
|
||
cargo test |
|
||
cargo build +---+---+
|
||
go test/build agent | |
|
||
2x DEB + 2x RPM + 2x SUSE RPM | |
|
||
APT + DNF + Zypper OPNsense FreeBSD native*
|
||
| | |
|
||
v v v
|
||
publikacja Linux os-rustproxy rustproxy.pkg
|
||
pkg repo pkg repo
|
||
|
||
* FreeBSD native: enabled by default; FREEBSD_NATIVE_ENABLED=0 disables it
|
||
```
|
||
|
||
`cargo test` i `go test ./...` (agenta) należą tylko do gałęzi Linux. Jeśli testy nie przejdą, DEB/RPM/SUSE nie są publikowane, ale builder nadal uruchamia cross-build FreeBSD i może opublikować repo OPNsense. Stan jest śledzony osobno w `last_linux_commit`, `last_opnsense_commit` i (jeśli włączone) `last_freebsd_commit`; kolejny cykl ponawia tylko brakującą gałąź.
|
||
|
||
## Docker Agent: osobne pakiety Linux
|
||
|
||
Builder sprawdza `docker-agent/go.mod`, uruchamia `go test ./...`, kompiluje statyczny agent z `CGO_ENABLED=0` dla `linux/amd64` i pakuje **niezależnie od głównego RustProxy**. Wersja paczki oraz wydrukowana wersja Go agenta są zgodne z `Cargo.toml` danego commita; `PACKAGE_RELEASE` jest wspólne dla obu produktów w jednym wydaniu. Build gałęzi Linux kończy się błędem, jeśli budowanie/testy agenta nie przejdą, więc nie opublikuje repo z niekompletną parą. OPNsense i natywne FreeBSD pozostają niezależne i bez agenta.
|
||
|
||
Zawartość katalogu `data/packages/` po udanym cyklu:
|
||
|
||
```text
|
||
data/packages/deb/rustproxy_<version>-<release>_amd64.deb
|
||
data/packages/deb/rustproxy-docker-agent_<version>-<release>_amd64.deb
|
||
data/packages/rpm/x86_64/rustproxy-<version>-<release>.x86_64.rpm
|
||
data/packages/rpm/x86_64/rustproxy-docker-agent-<version>-<release>.x86_64.rpm
|
||
data/packages/suse/x86_64/rustproxy-<version>-<release>.x86_64.rpm
|
||
data/packages/suse/x86_64/rustproxy-docker-agent-<version>-<release>.x86_64.rpm
|
||
```
|
||
|
||
Wszystkie pakiety (DEB, DNF RPM i SUSE RPM) są podpisane istniejącym kluczem GPG repozytorium; metadane obu repozytoriów RPM również są podpisane. Każde repo zawiera `rustproxy` i `rustproxy-docker-agent`. Zmiana rewizji pakowania Linux (`PACKAGING_REVISION=6`) wymusza przebudowę także dla niezmienionego commita.
|
||
|
||
Instalacja na hoście Docker (uruchom Docker Engine wcześniej):
|
||
|
||
```bash
|
||
# Debian / Ubuntu, po dodaniu repo APT
|
||
sudo apt update
|
||
sudo apt install rustproxy-docker-agent
|
||
|
||
# RHEL / Rocky / Alma / Fedora, po dodaniu repo DNF
|
||
sudo dnf install rustproxy-docker-agent
|
||
|
||
# Konfiguracja w panelu RustProxy: Settings -> Docker agents
|
||
sudo rustproxy-docker-agent info
|
||
sudo rustproxy-docker-agent info --show-token
|
||
sudo rustproxy-docker-agent print-fingerprint
|
||
sudo systemctl status rustproxy-docker-agent
|
||
```
|
||
|
||
Instalacja z lokalnego pliku: `sudo apt install ./rustproxy-docker-agent_*.deb` lub `sudo dnf install ./rustproxy-docker-agent-*.rpm` (jedna pasująca wersja w katalogu). Dla pakietu nie trzeba mieć kompilatora Go. Skrypty `postinstall` zakładają konto systemowe, zabezpieczają `/etc/rustproxy/docker-agent.env`, inicjalizują długi losowy token oraz samopodpisany certyfikat i uruchamiają systemd, jeśli Docker socket jest dostępny. Tokenu **nie wypisują do logów dpkg/rpm**. `info --show-token` wywołuje administrator świadomie, lokalnie.
|
||
|
||
Konfiguracja i klucze pozostają po aktualizacji: `/etc/rustproxy/docker-agent.env` (`config|noreplace`, finalnie `0600`) oraz `/var/lib/rustproxy-docker-agent/agent.crt` i `agent.key` (klucz `0600`). Rotacja przez `sudo rustproxy-docker-agent rotate-token` wymaga `sudo systemctl restart rustproxy-docker-agent` i aktualizacji tokenu w panelu RustProxy. Do ręcznej instalacji, bez pakietu, pozostaje `cd docker-agent && sudo ./install.sh` po sklonowaniu projektu z Go 1.22+; instrukcje: `docker-agent/README.md` w repo RustProxy.
|
||
|
||
W przypadku przechodzenia z instalacji ręcznej na paczkę: jednostka w `/etc/systemd/system/rustproxy-docker-agent.service` ma pierwszeństwo przed jednostką paczkowaną w `/usr/lib/systemd/system`. Należy zachować token/certyfikat, zatrzymać usługę, przenieść ręczną jednostkę poza katalog systemd i wykonać `systemctl daemon-reload` przed zainstalowaniem paczki. Głównego `rustproxy` i jego konfiguracji to nie dotyczy.
|
||
|
||
## SUSE / openSUSE / openSUSE Leap — RPM / Zypper
|
||
|
||
Gałąź Linux buduje dodatkowo **dwie natywne paczki RPM dla SUSE** z tego samego commita: `rustproxy` i `rustproxy-docker-agent`. Mają inne zależności niż paczki dla RHEL (m.in. `shadow` zamiast `shadow-utils`) i oddzielne, podpisane repozytorium `suse/x86_64` z metadanymi `repomd.xml.asc` oraz informacją `SUSE-BUILD-INFO.txt`. DNF/YUM nie jest zmieniany. Paczki SUSE mają kompresję gzip dla zgodności ze starszymi klientami RPM.
|
||
|
||
Dla systemów SUSE z Pythonem systemowym starszym niż 3.10 paczka serwera dopuszcza doinstalowanie wersjonowanego Pythona (z `pip`), np. `python311` i `python311-pip`. Lokalny wrapper `/usr/libexec/rustproxy/python3` jest dodawany wyłącznie do ścieżki `PATH` usługi RustProxy przez drop-in systemd. **Nie podmienia** systemowego `/usr/bin/python3`. Zalecane środowiska: **SLES 15 SP6/SP7 i nowsze**, **SLES 16**, **openSUSE Leap 15.6 i 16.x**, **openSUSE Tumbleweed** z architekturą x86_64 i `glibc >= 2.34`. Dla starszych wydań z glibc 2.31 (np. SLES 15 SP5) paczka nie jest kompatybilna bez osobnego builda na starszym toolchainie. Zależności dla konkretnej wersji sprawdź przez `zypper` przed wdrożeniem.
|
||
|
||
Instalacja po pierwszej publikacji (zamień `REPOSITORY_URL` na adres serwera pakietów):
|
||
|
||
```sh
|
||
sudo rpm --import REPOSITORY_URL/repo-key.gpg
|
||
sudo zypper addrepo --refresh --gpgcheck REPOSITORY_URL/suse/x86_64/ rustproxy-suse
|
||
sudo zypper refresh rustproxy-suse
|
||
sudo zypper install rustproxy
|
||
# Opcjonalnie, na hoście z Docker Engine:
|
||
sudo zypper install rustproxy-docker-agent
|
||
```
|
||
|
||
Aktualizacja: `sudo zypper update rustproxy rustproxy-docker-agent` (agent tylko gdy zainstalowany). Pakiety i repozytorium są publikowane atomowo wraz z APT/DNF jako część gałęzi Linux. Jeśli builder miał już wydanie z tą samą wersją, `PACKAGING_REVISION=6` wymusi jednorazową przebudowę; gałęzie OPNsense/FreeBSD zachowują dotychczasowy stan. **Paczki RPM nie znajdują się w samym archiwum projektu** — powstają po uruchomieniu buildera na źródłach RustProxy.
|
||
|
||
## OPNsense repo
|
||
|
||
Publiczny root `OPNSENSE_REPOSITORY_URL` zawiera m.in.:
|
||
|
||
```text
|
||
/
|
||
├── meta.conf
|
||
├── packagesite.pkg
|
||
├── data.pkg
|
||
├── RustProxy.conf
|
||
├── BUILD-INFO.txt
|
||
├── SHA256
|
||
├── os-rustproxy-latest.pkg
|
||
└── 26.7/
|
||
└── amd64/
|
||
├── os-rustproxy-0.20.0_123.pkg
|
||
└── ...
|
||
```
|
||
|
||
`RustProxy.conf` jest generowany automatycznie i wskazuje na `OPNSENSE_REPOSITORY_URL`. Repo OPNsense jest obecnie niesygnowane, zgodnie z wcześniejszym builderem/repo (`signature_type: "none"`). Repo APT/RPM pozostaje podpisane GPG.
|
||
|
||
Ręczna konfiguracja na OPNsense:
|
||
|
||
```sh
|
||
mkdir -p /usr/local/etc/pkg/repos
|
||
fetch -o /usr/local/etc/pkg/repos/RustProxy.conf \
|
||
https://opn-rustproxy.linuxiarz.pl/RustProxy.conf
|
||
pkg update -f
|
||
pkg install os-rustproxy
|
||
```
|
||
|
||
## Konfiguracja
|
||
|
||
Najważniejsze zmienne:
|
||
|
||
```env
|
||
SOURCE_REPO=https://git.linuxiarz.pl/gru/RustProxy.git
|
||
SOURCE_BRANCH=master
|
||
|
||
REPOSITORY_URL=http://192.168.1.100
|
||
HTTP_PORT=18765
|
||
|
||
OPNSENSE_REPOSITORY_URL=https://opn-rustproxy.linuxiarz.pl
|
||
OPNSENSE_HTTP_PORT=18766
|
||
|
||
POLL_INTERVAL=300
|
||
PACKAGE_RELEASE=auto
|
||
MAX_GLIBC_VERSION=2.34
|
||
RUN_LINUX_TESTS=1
|
||
|
||
OPNSENSE_ABI=26.7
|
||
OPNSENSE_RETENTION=10
|
||
FREEBSD_RELEASE=15.1-RELEASE
|
||
FREEBSD_ABI=FreeBSD:15:amd64
|
||
FREEBSD_ARCH=freebsd:15:x86:64
|
||
FREEBSD_RUST_TOOLCHAIN=1.88.0
|
||
APPLY_FREEBSD_PATCHES=1
|
||
```
|
||
|
||
`RUN_LINUX_TESTS=1` jest domyślne. Testy są bramką tylko dla DEB/RPM/SUSE i nie wpływają na gałąź OPNsense. Ustaw `0`, jeśli chcesz całkowicie pominąć testy Linux.
|
||
|
||
`OPNSENSE_RETENTION=10` zachowuje ostatnie 10 wersji pakietu dla danej serii/architektury OPNsense. `0` wyłącza usuwanie starych wersji.
|
||
|
||
`FREEBSD_NATIVE_ENABLED=1` (domyślnie) włącza natywny pakiet FreeBSD i oddzielny kanał publikacji. `0` wyłącza budowanie natywnego FreeBSD. **Uwaga przy aktualizacji:** istniejący plik `.env` z `FREEBSD_NATIVE_ENABLED=0` ma pierwszeństwo przed nową wartością domyślną — zmień go ręcznie na `1`, inaczej pakiet FreeBSD nadal nie powstanie. `FREEBSD_NATIVE_RETENTION=10` ogranicza liczbę zachowanych wersji. Repo używa tego samego publicznego hosta/portu co OPNsense, ale pod oddzielnym prefiksem `OPNSENSE_REPOSITORY_URL/freebsd/`.
|
||
|
||
## Automatyczny Rust toolchain podczas budowania
|
||
|
||
Builder sprawdza `rust-version` w `Cargo.toml` **pobranego commita** i opcjonalny
|
||
`rust-toolchain.toml`/`rust-toolchain` przed kompilacją każdej gałęzi.
|
||
|
||
- **Linux DEB/RPM:** używa istniejącego `stable`; wywołuje `rustup` tylko,
|
||
gdy brakuje toolchainu albo wersja jest starsza od wymaganej przez projekt.
|
||
- **FreeBSD/OPNsense:** `FREEBSD_RUST_TOOLCHAIN` pozostaje bazowym toolchainem.
|
||
Gdy jest starszy od `rust-version`, builder automatycznie dobiera wersję
|
||
minimalną projektu oraz doinstalowuje target `x86_64-unknown-freebsd`.
|
||
- Jeśli projekt przypina konkretny toolchain, builder **respektuje pin**.
|
||
Sprzeczny pin i `rust-version` powodują czytelny błąd zamiast cichej zmiany.
|
||
- Testy i build danej gałęzi używają tego samego wybranego toolchainu.
|
||
- Aktualizacja nie zmienia globalnego `rustup default`, systemowych pakietów
|
||
ani wersji już opublikowanych pakietów RustProxy.
|
||
- Toolchainy pobrane w trakcie działania są w warstwie kontenera
|
||
(`/opt/rustup`); po **odtworzeniu kontenera** mogą wymagać ponownego pobrania.
|
||
Cache Cargo w `data/cargo` pozostaje trwały.
|
||
- Jeśli pobranie toolchainu lub kompilacja się nie powiedzie, dany kanał
|
||
nie zostaje opublikowany; pozostały kanał builder obsługuje niezależnie.
|
||
|
||
Działanie nie wymaga nowej opcji w `.env`. Uruchom `./start.sh`, żeby
|
||
przebudować obraz z nowym skryptem. Aktualizacje toolchainu na podstawie
|
||
źródeł będą potem automatyczne przy kolejnych buildach.
|
||
|
||
## FreeBSD cross-build
|
||
|
||
Obraz buildera pobiera i weryfikuje `base.txz` dla `FREEBSD_RELEASE`, a następnie używa:
|
||
|
||
```text
|
||
/opt/freebsd-sysroot
|
||
clang / lld / llvm
|
||
Rust target x86_64-unknown-freebsd
|
||
```
|
||
|
||
Poprawki tylko dla builda OPNsense są w:
|
||
|
||
```text
|
||
opnsense/patches/<wersja-RustProxy>/*.patch
|
||
```
|
||
|
||
Są nakładane na izolowaną kopię źródła. Build Linux nie jest modyfikowany.
|
||
|
||
Kod pluginu OPNsense znajduje się w:
|
||
|
||
```text
|
||
opnsense/plugin/
|
||
```
|
||
|
||
## OPNsense: autostart i sprawdzanie aktualizacji aplikacji
|
||
|
||
W **Services -> RustProxy** zaznacz **Enabled** i naciśnij **Apply**. Pakiet
|
||
instaluje wykonywalny syshook w
|
||
`/usr/local/etc/rc.syshook.d/start/50-rustproxy.start`. Po restarcie systemu,
|
||
gdy sieć już działa, hook odświeża konfigurację z OPNsense i uruchamia usługę
|
||
tylko wtedy, gdy jest włączona. Powtórny start nie tworzy drugiego procesu.
|
||
|
||
Pole **Update check interval (seconds)** steruje argumentem RustProxy
|
||
`--update-check-interval-secs`. Domyślnie `3600` (godzina); dopuszczalny zakres
|
||
to `60`–`604800` sekund. Wartość nie dotyczy `POLL_INTERVAL` buildera,
|
||
który nadal odpowiada wyłącznie za sprawdzanie repozytorium kodu.
|
||
|
||
Sprawdzenie po restarcie OPNsense:
|
||
|
||
```sh
|
||
ls -l /usr/local/etc/rc.syshook.d/start/50-rustproxy.start
|
||
configctl rustproxy status
|
||
cat /var/run/rustproxy/command.txt
|
||
```
|
||
|
||
W `command.txt` powinien wystąpić aktualnie ustawiony parametr
|
||
`--update-check-interval-secs <liczba>`. Jeśli usługa nie wystartuje, sprawdź
|
||
`/var/log/rustproxy/rustproxy.log` oraz uruchom ręcznie:
|
||
|
||
```sh
|
||
configctl template reload OPNsense/RustProxy
|
||
configctl rustproxy start
|
||
```
|
||
|
||
Obsługa miękkiego przeładowania zwiększa `OPNSENSE_PACKAGING_REVISION` do `4`.
|
||
Pakowanie Linux ma `PACKAGING_REVISION=6`, a natywne FreeBSD `FREEBSD_NATIVE_PACKAGING_REVISION=2`. Każdy kanał otrzymuje osobną aktualizację przy zmianie swojej rewizji.
|
||
|
||
## DEB/RPM: dostęp do plików strony i zewnętrznych certyfikatów
|
||
|
||
Od rewizji pakowania **5** jednostka `rustproxy.service` używa
|
||
`ProtectHome=read-only` zamiast `ProtectHome=true`. Dzięki temu katalogi
|
||
`/home/...`, `/var/www/...` i `/srv/...` mogą być czytane na podstawie
|
||
normalnych uprawnień grupowych lub ACL, bez lokalnych wyjątków systemd.
|
||
`ProtectSystem=strict` nadal chroni te lokalizacje przed zapisem. Builder
|
||
normalizuje również `ProtectHome` w starszym `debian/rustproxy.service`, jeśli
|
||
taki plik istnieje w pobranym źródle; sama rewizja pakowania wystarcza do
|
||
ponownego zbudowania DEB/RPM przy niezmienionym kodzie aplikacji.
|
||
|
||
Instrukcja trafia **do obu paczek** jako
|
||
`/usr/share/doc/rustproxy/FILESYSTEM_ACCESS.md` (źródło:
|
||
[`packaging/rustproxy-filesystem-access.md`](packaging/rustproxy-filesystem-access.md)).
|
||
Opisuje bezpieczne przyznanie grupy lub ACL, odświeżenie grup przez restart,
|
||
obsługę certyfikatów Certbot i ich symlinków oraz ograniczenie aplikacyjne:
|
||
zewnętrzne PEM wymagają zaufanych katalogów właściciela `root`/`rustproxy`.
|
||
Pakiet nie przypisuje automatycznie szerokich grup do użytkownika usługi,
|
||
nie zmienia uprawnień witryn ani nie nadpisuje istniejących drop-inów.
|
||
|
||
Test pakowania jest dostępny w pełnym repozytorium developerskim (nie jest dołączony do archiwum wdrożeniowego).
|
||
|
||
## Rotacja logów RustProxy
|
||
|
||
- **DEB/RPM:** builder zawsze umieszcza `packaging/rustproxy.logrotate` w `/etc/logrotate.d/rustproxy` (nFPM: `config|noreplace`). Logrotate jest zależnością obu pakietów. Reguła obejmuje `/var/log/rustproxy/*.jsonl`, `*.log` i `vhosts/*.jsonl`, z rotacją codzienną lub po przekroczeniu 100 MiB, 14 archiwami, gzip z opóźnioną kompresją, `copytruncate` oraz `su rustproxy rustproxy`.
|
||
- **OPNsense / natywne FreeBSD PKG:** pakiet dostarcza `/usr/local/etc/newsyslog.conf.d/rustproxy.conf` dla tych samych ścieżek; `newsyslog` wykonuje rotację codziennie lub przy rozmiarze 100 MiB, przechowuje 14 archiwów, pomija puste pliki i używa gzip z niekompresowanym najnowszym archiwum. Plik `*.log` jest ponownie otwierany przez `daemon(8)` po `SIGHUP` (opcja `-H` w skrypcie rc.d). OPNsense uruchamia usługę jako `root` (`root:wheel` w `newsyslog`); natywne FreeBSD działa jako `rustproxy` (`rustproxy:rustproxy` w `newsyslog`).
|
||
|
||
**Uwaga FreeBSD:** `newsyslog` działa przez zmianę nazwy pliku, nie ma `copytruncate`. Pliki JSONL i inne logi otwarte bezpośrednio przez aplikację muszą być przez nią ponownie otwierane po rotacji. W przeciwnym razie proces może pisać do poprzedniego (przeniesionego) pliku; zachowanie nie jest identyczne z Linux. Reguły są instalowane, ale na działającym OPNsense należy zweryfikować sposób otwierania plików przez RustProxy.
|
||
|
||
Bieżąca rewizja pakowania Linux wynosi `PACKAGING_REVISION=6` i `OPNSENSE_PACKAGING_REVISION=4`; nowy kanał używa `FREEBSD_NATIVE_PACKAGING_REVISION=2`. `check-and-build.sh` sprawdza osobno rewizje pakowania Linux, OPNsense i FreeBSD native; nowa wersja samej wtyczki przebudowuje **tylko OPNsense**, nawet przy niezmienionym SHA aplikacji. Rewizja pakietu PKG zwiększy się automatycznie. W przypadku zmiany rewizji Linux analogicznie odświeżane są DEB/RPM. Konfiguracja w `/etc/logrotate.d/rustproxy` jest oznaczona jako `noreplace`, więc lokalna wersja zmodyfikowana przez administratora może zostać zachowana (zależnie od menedżera pakietów).
|
||
|
||
Kontrola po zainstalowaniu:
|
||
|
||
```sh
|
||
# DEB / RPM (nie wykonuje rotacji)
|
||
logrotate -d /etc/logrotate.d/rustproxy
|
||
|
||
# OPNsense (nie wykonuje rotacji)
|
||
newsyslog -n -v -f /usr/local/etc/newsyslog.conf.d/rustproxy.conf
|
||
```
|
||
|
||
Testy integracyjne są dostępne w pełnym repozytorium developerskim.
|
||
|
||
## Dane
|
||
|
||
```text
|
||
data/
|
||
├── aptly/
|
||
├── cargo/
|
||
├── packages/
|
||
│ ├── deb/
|
||
│ └── rpm/x86_64/
|
||
├── repository/
|
||
│ ├── current -> releases/<build>
|
||
│ ├── apt -> current/apt
|
||
│ ├── rpm -> current/rpm
|
||
│ ├── opnsense -> current/opnsense
|
||
│ ├── freebsd -> current/freebsd
|
||
│ └── releases/
|
||
├── state/
|
||
└── work/
|
||
```
|
||
|
||
Każda publikacja tworzy nowy snapshot `repository/releases/...` i atomowo przełącza `current`. Przy publikacji jednego kanału poprzednie katalogi pozostałych kanałów są zachowywane. Dzięki temu wszystkie aktywne kanały są niezależne, ale nginx nadal serwuje jeden spójny snapshot katalogu.
|
||
|
||
## HTTP i logi
|
||
|
||
Jeden kontener nginx obsługuje repo Linux i repo OPNsense na dwóch lokalnych portach; natywne FreeBSD jest serwowane jako `/freebsd/` na porcie OPNsense:
|
||
|
||
```bash
|
||
docker compose logs -f rust-package-builder
|
||
docker compose logs -f repository-http
|
||
|
||
curl -f http://127.0.0.1:18765/healthz
|
||
curl -f http://127.0.0.1:18766/healthz
|
||
```
|
||
|
||
## Testy statyczne
|
||
|
||
Skrypty diagnostyczne są dostępne w pełnym repozytorium developerskim; wydanie wdrożeniowe zawiera tylko pliki potrzebne do uruchomienia.
|
||
|
||
## Klucz GPG
|
||
|
||
`./start.sh` generuje trwały klucz GPG przy pierwszym uruchomieniu. Katalogu `gpg/` nie należy usuwać po publikacji APT/RPM.
|
||
|
||
## Migracja ze starszego buildera Linux-only
|
||
|
||
Builder używa osobnych stanów:
|
||
|
||
```text
|
||
data/state/last_linux_commit
|
||
data/state/last_opnsense_commit
|
||
```
|
||
|
||
Jeżeli istnieje starsze `last_commit` oraz poprawne APT/RPM dla tego SHA, zostanie ono potraktowane jako stan gałęzi Linux. Brak repo OPNsense uruchomi wyłącznie gałąź OPNsense. Po udanym OPNsense kolejny cykl nie będzie ponownie kompilował FreeBSD, nawet jeśli testy Linux nadal nie przechodzą.
|
||
|
||
## FreeBSD patch version detection
|
||
|
||
The OPNsense branch reuses the Cargo package `VERSION` already detected by the main build pipeline. If `apply-freebsd-patches.sh` is run manually, it falls back to `RUST_PROXY_PYTHON` (`/usr/bin/python3.11`) so Rocky Linux 9's default Python 3.9 does not cause a missing `tomllib` error.
|
||
|
||
### Czyszczenie cache Cargo
|
||
|
||
Po **udanym opublikowaniu pakietów** każdej gałęzi (Linux/OPNsense/FreeBSD native) builder
|
||
usuwa `target/**/incremental` i `target/debug`, a także pliki starsze
|
||
niż 30 dni z `target/release/deps` oraz
|
||
`target/x86_64-unknown-freebsd/release/deps`. Zachowuje aktualne artefakty
|
||
release, fingerprinty oraz cache zależności, więc kolejne buildy nie startują
|
||
od zera. Starsze usunięte zależności mogą wymagać pojedynczej rekompilacji.
|
||
|
||
Ustawienia środowiskowe: `CLEAN_TARGET_AFTER_BUILD=0` wyłącza czyszczenie;
|
||
`TARGET_CACHE_MAX_AGE_DAYS=30` określa wiek nieużywanych plików.
|
||
|
||
|
||
## RustProxy 0.34.x: plik `--config` i miękki reload
|
||
|
||
- **Linux DEB/RPM:** gdy usługa systemd nie ma własnego `ExecReload`, builder dodaje wywołanie `rust-proxy --data-dir /var/lib/rustproxy --admin-listen 127.0.0.1:9090 reload`. `systemctl reload rustproxy` wykonuje przeładowanie przez administracyjne API, nie restartuje procesu. Usługi z `ProtectSystem=strict` otrzymują dodatkowo zapis do `-/etc/rustproxy`. Aby panel mógł zapisywać wskazany `--config`, plik i jego katalog muszą być własnością użytkownika usługi. Przykładowo można ustawić `RUST_PROXY_CONFIG=/etc/rustproxy/config.json` w `/etc/rustproxy/environment`, po uprzednim utworzeniu poprawnego pliku JSON.
|
||
- **OPNsense:** `configctl rustproxy reload` wykonuje miękkie przeładowanie z CLI. Skrypt `service.sh` nie robi już stop/start dla `reload`. Listener GUI po zmianie adresu/portu wymaga nadal `restart`, ponieważ samo przeładowanie nie zmienia gniazd nasłuchujących. Opcjonalna ścieżka `rustproxy_config_path` w `rc.conf` (absolutna, bez spacji) jest przekazywana jako `--config`; panel OPNsense nie ma jeszcze osobnego pola do jej edycji. CLI wymaga osiągalnego adresu administratora na loopback.
|
||
- **Czystemu FreeBSD** służy osobna paczka `rustproxy`, bez modeli MVC, configd, syshooków i pluginu OPNsense. Jej natywne `rc.d` uruchamia usługę na koncie `rustproxy`, domyślnie nasłuchuje na HTTP `8080`, admin na `127.0.0.1:9090`, a TLS jest domyślnie wyłączony. Po `sysrc rustproxy_enable=YES` można wykonać `service rustproxy start`, `service rustproxy reload` i `service rustproxy restart`. Ścieżkę JSON można przekazać przez `sysrc rustproxy_config=/usr/local/etc/rustproxy/config.json` po przygotowaniu prawidłowego pliku z uprawnieniami użytkownika `rustproxy`.
|
||
|
||
**Ważne:** CLI `reload` wymaga uruchomionego RustProxy, zainicjalizowanego administratora i API osiągalnego przez adres loopback. Zmiana adresów/portów nasłuchujących wymaga `restart`, a nie `reload`.
|
||
|
||
## Natywne repo FreeBSD — włączone domyślnie
|
||
|
||
Dla nowej instalacji FreeBSD native włącza się automatycznie. Jeśli masz już `.env`, **sprawdź**, czy ma:
|
||
|
||
```env
|
||
FREEBSD_NATIVE_ENABLED=1
|
||
FREEBSD_NATIVE_RETENTION=10
|
||
```
|
||
|
||
Następnie `./start.sh` (przebudowa kontenerów buildera i panelu). Natywna paczka pojawi się pod:
|
||
|
||
```text
|
||
${OPNSENSE_REPOSITORY_URL}/freebsd/
|
||
RustProxy-FreeBSD.conf
|
||
meta.conf
|
||
packagesite.pkg
|
||
data.pkg
|
||
rustproxy-latest.pkg
|
||
FreeBSD:15:amd64/rustproxy-<wersja>_<revision>.pkg
|
||
```
|
||
|
||
Na **czystym FreeBSD 15 amd64**:
|
||
|
||
```sh
|
||
mkdir -p /usr/local/etc/pkg/repos
|
||
fetch -o /usr/local/etc/pkg/repos/RustProxy-FreeBSD.conf \
|
||
https://YOUR-OPNSENSE-REPO-HOST/freebsd/RustProxy-FreeBSD.conf
|
||
pkg update -f
|
||
pkg install rustproxy
|
||
sysrc rustproxy_enable=YES
|
||
service rustproxy start
|
||
service rustproxy reload
|
||
```
|
||
|
||
To osobny pakiet od `os-rustproxy`: nie należy instalować obu pakietów naraz, bo oba używają nazwy usługi i ścieżek RustProxy.
|
||
|
||
**Bezpieczeństwo repo:** aktualnie katalog `pkg` jest **niesygnowany**, analogicznie do istniejącego repo OPNsense (`signature_type: none`). To nadaje się do testów DEV na zaufanej infrastrukturze. Przed produkcyjnym wdrożeniem należy dodać podpis katalogu `pkg`, bezpieczną dystrybucję klucza publicznego i wykonać instalację oraz aktualizację na rzeczywistym FreeBSD. Generator katalogu korzysta z formatu repozytorium `pkg` w wersji **2** dla FreeBSD 15 (OPNsense zachowuje dotychczasowy format), ale testy offline nie zastępują testu klienta `pkg` na prawdziwym FreeBSD.
|
||
|
||
Pakietowe testy offline są dostępne w pełnym repozytorium developerskim (nie w wydaniu wdrożeniowym).
|
||
|
||
|
||
## Troubleshooting: no native FreeBSD build
|
||
|
||
1. Ensure `.env` contains `FREEBSD_NATIVE_ENABLED=1` (older installations often set `0`).
|
||
2. Rebuild/start: `docker compose --env-file .env up -d --build rust-package-builder repository-dashboard`.
|
||
3. Follow the builder logs: `docker compose --env-file .env logs -f rust-package-builder`.
|
||
4. Look for `build plan: ... freebsd=1` and then `FreeBSD native publication completed:`. If compilation fails, inspect the **first** `error:` in the same log. The OPNsense package uses the same FreeBSD cross-compiled executable but native FreeBSD publishes independently.
|
||
5. Check `data/repository/current/freebsd/BUILD-INFO.txt` and `data/repository/current/freebsd/meta.conf` (`version: 2;`). The API `/api/v1/packages` then shows the published FreeBSD package/version/build time.
|
||
|
||
The development test `tests/freebsd-release.sh` uses a simulated ELF to verify packaging/catalog/atomic publication without Docker. It **does not prove Rust compilation or installation on real FreeBSD**. For end-to-end validation, run `pkg update -f` and `pkg install rustproxy` on FreeBSD 15.1 amd64 against the published URL. The catalog is **not signed**, so only use a trusted HTTPS source during testing.
|