feat: add OpenWrt cross-compilation and packaging (Phase F7)
- 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
This commit is contained in:
146
docs/openwrt.md
Normal file
146
docs/openwrt.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user