quicproquo/docs/openwrt.md

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

# Install cargo-zigbuild (recommended — no Docker required)
pip3 install ziglang
cargo install cargo-zigbuild

Cross-Compilation

Quick Start

# Build for all supported targets
./scripts/cross-compile.sh

# Build for a specific target
./scripts/cross-compile.sh aarch64-unknown-linux-musl

Manual Build

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

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

# 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

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