Christian Nennemann
2e081ead8e
Rename all project references from quicproquo/qpq to quicprochat/qpc across documentation, Docker configuration, CI workflows, packaging scripts, operational configs, and build tooling. - Docker: crate paths, binary names, user/group, data dirs, env vars - CI: workflow crate references, binary names, artifact names - Docs: all markdown files under docs/, SDK READMEs, book.toml - Packaging: OpenWrt Makefile, init script, UCI config (file renames) - Scripts: justfile, dev-shell, screenshot, cross-compile, ai_team - Operations: Prometheus config, alert rules, Grafana dashboard - Config: .env.example (QPQ_* → QPC_*), CODEOWNERS paths - Top-level: README, CONTRIBUTING, ROADMAP, CLAUDE.md
147 lines
4.5 KiB
Markdown
147 lines
4.5 KiB
Markdown
# OpenWrt Deployment Guide
|
|
|
|
Run quicprochat 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 qpc-server
|
|
```
|
|
|
|
The binary lands at `target/<triple>/release/qpc-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/qpc-server root@router:/usr/bin/
|
|
|
|
# Copy init script and config
|
|
scp packaging/openwrt/files/quicprochat.init root@router:/etc/init.d/quicprochat
|
|
scp packaging/openwrt/files/quicprochat.uci root@router:/etc/config/quicprochat
|
|
|
|
# Enable and start
|
|
ssh root@router 'chmod +x /etc/init.d/quicprochat && /etc/init.d/quicprochat enable && /etc/init.d/quicprochat 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 quicprochat /path/to/quicprochat/packaging/openwrt" >> feeds.conf
|
|
|
|
# Update and install
|
|
./scripts/feeds update quicprochat
|
|
./scripts/feeds install quicprochat
|
|
|
|
# Select in menuconfig: Network -> quicprochat
|
|
make menuconfig
|
|
make package/quicprochat/compile V=s
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The server is configured via UCI at `/etc/config/quicprochat`:
|
|
|
|
```
|
|
config server 'server'
|
|
option listen '0.0.0.0:7000'
|
|
option data_dir '/var/lib/quicprochat'
|
|
option log_level 'info'
|
|
option tls_cert '/var/lib/quicprochat/server-cert.der'
|
|
option tls_key '/var/lib/quicprochat/server-key.der'
|
|
option production '1'
|
|
```
|
|
|
|
### UCI Options
|
|
|
|
| Option | Default | Description |
|
|
|--------------|------------------------------------------|----------------------------------|
|
|
| `listen` | `0.0.0.0:7000` | QUIC listen address |
|
|
| `data_dir` | `/var/lib/quicprochat` | 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/quicprochat start
|
|
/etc/init.d/quicprochat stop
|
|
/etc/init.d/quicprochat restart
|
|
|
|
# Enable at boot
|
|
/etc/init.d/quicprochat enable
|
|
|
|
# View logs
|
|
logread -e quicprochat
|
|
```
|
|
|
|
## 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.
|