Christian Nennemann
372dd67a3b
- packaging/openwrt/: opkg Makefile, procd init script, uci config - scripts/cross-compile.sh: build for musl targets with size checks - .github/workflows/openwrt.yml: CI cross-compile + 5 MB size gate - docs/openwrt.md: installation and configuration guide - Targets: x86_64-musl, armv7-musleabihf, aarch64-musl - Uses cargo-zigbuild for Docker-free cross-compilation
147 lines
4.5 KiB
Markdown
147 lines
4.5 KiB
Markdown
# OpenWrt Deployment Guide
|
|
|
|
Run quicproquo on OpenWrt routers for mesh-capable, always-on encrypted messaging at the network edge.
|
|
|
|
## Supported Targets
|
|
|
|
| Target | Architecture | Common Devices |
|
|
|-----------------------------------|----------------|--------------------------|
|
|
| `x86_64-unknown-linux-musl` | x86_64 | PC Engines APU, VMs |
|
|
| `armv7-unknown-linux-musleabihf` | ARMv7 (hard-float) | RPi 2/3, many routers |
|
|
| `aarch64-unknown-linux-musl` | AArch64 | RPi 4/5, modern routers |
|
|
|
|
## Prerequisites
|
|
|
|
- Rust toolchain (stable)
|
|
- One of: `cargo-zigbuild` (recommended) or `cross`
|
|
|
|
```bash
|
|
# Install cargo-zigbuild (recommended — no Docker required)
|
|
pip3 install ziglang
|
|
cargo install cargo-zigbuild
|
|
```
|
|
|
|
## Cross-Compilation
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
# Build for all supported targets
|
|
./scripts/cross-compile.sh
|
|
|
|
# Build for a specific target
|
|
./scripts/cross-compile.sh aarch64-unknown-linux-musl
|
|
```
|
|
|
|
### Manual Build
|
|
|
|
```bash
|
|
# Add the musl target
|
|
rustup target add x86_64-unknown-linux-musl
|
|
|
|
# Size-optimised release build
|
|
CARGO_PROFILE_RELEASE_OPT_LEVEL=s \
|
|
CARGO_PROFILE_RELEASE_LTO=true \
|
|
CARGO_PROFILE_RELEASE_CODEGEN_UNITS=1 \
|
|
CARGO_PROFILE_RELEASE_STRIP=symbols \
|
|
cargo zigbuild --release --target x86_64-unknown-linux-musl --bin qpq-server
|
|
```
|
|
|
|
The binary lands at `target/<triple>/release/qpq-server`. Target size: under 5 MB.
|
|
|
|
## OpenWrt Package Installation
|
|
|
|
### Option 1: Direct binary install (quick)
|
|
|
|
```bash
|
|
# Copy binary to router
|
|
scp target/aarch64-unknown-linux-musl/release/qpq-server root@router:/usr/bin/
|
|
|
|
# Copy init script and config
|
|
scp packaging/openwrt/files/quicproquo.init root@router:/etc/init.d/quicproquo
|
|
scp packaging/openwrt/files/quicproquo.uci root@router:/etc/config/quicproquo
|
|
|
|
# Enable and start
|
|
ssh root@router 'chmod +x /etc/init.d/quicproquo && /etc/init.d/quicproquo enable && /etc/init.d/quicproquo start'
|
|
```
|
|
|
|
### Option 2: opkg package feed
|
|
|
|
Add the feed to your OpenWrt build system:
|
|
|
|
```bash
|
|
# In your OpenWrt buildroot, add to feeds.conf:
|
|
echo "src-link quicproquo /path/to/quicproquo/packaging/openwrt" >> feeds.conf
|
|
|
|
# Update and install
|
|
./scripts/feeds update quicproquo
|
|
./scripts/feeds install quicproquo
|
|
|
|
# Select in menuconfig: Network -> quicproquo
|
|
make menuconfig
|
|
make package/quicproquo/compile V=s
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The server is configured via UCI at `/etc/config/quicproquo`:
|
|
|
|
```
|
|
config server 'server'
|
|
option listen '0.0.0.0:7000'
|
|
option data_dir '/var/lib/quicproquo'
|
|
option log_level 'info'
|
|
option tls_cert '/var/lib/quicproquo/server-cert.der'
|
|
option tls_key '/var/lib/quicproquo/server-key.der'
|
|
option production '1'
|
|
```
|
|
|
|
### UCI Options
|
|
|
|
| Option | Default | Description |
|
|
|--------------|------------------------------------------|----------------------------------|
|
|
| `listen` | `0.0.0.0:7000` | QUIC listen address |
|
|
| `data_dir` | `/var/lib/quicproquo` | Persistent data directory |
|
|
| `log_level` | `info` | RUST_LOG filter |
|
|
| `tls_cert` | `<data_dir>/server-cert.der` | TLS certificate path (DER) |
|
|
| `tls_key` | `<data_dir>/server-key.der` | TLS private key path (DER) |
|
|
| `production` | `1` | Enable production hardening |
|
|
|
|
### Service Management
|
|
|
|
```bash
|
|
# Start / stop / restart
|
|
/etc/init.d/quicproquo start
|
|
/etc/init.d/quicproquo stop
|
|
/etc/init.d/quicproquo restart
|
|
|
|
# Enable at boot
|
|
/etc/init.d/quicproquo enable
|
|
|
|
# View logs
|
|
logread -e quicproquo
|
|
```
|
|
|
|
## Binary Size Optimization
|
|
|
|
The release profile is configured for minimal binary size:
|
|
|
|
| Setting | Value | Effect |
|
|
|------------------|------------|-------------------------------------|
|
|
| `opt-level` | `s` | Optimize for size over speed |
|
|
| `lto` | `true` | Full link-time optimization |
|
|
| `codegen-units` | `1` | Single codegen unit for better LTO |
|
|
| `strip` | `symbols` | Remove debug symbols |
|
|
|
|
The CI workflow enforces a 5 MB maximum binary size on every release tag.
|
|
|
|
## CI/CD
|
|
|
|
The `.github/workflows/openwrt.yml` workflow automatically:
|
|
|
|
1. Cross-compiles for all three musl targets
|
|
2. Verifies binary size stays under 5 MB
|
|
3. Uploads binaries as release artifacts
|
|
|
|
Triggered on version tags (`v*`) or manual dispatch.
|