Release Engineering & Packaging Reference

This document describes the release packaging, artifact verification, filesystem layout, systemd service hardening, and distribution model for nx9-wg.

1. Release Packaging Pipeline

Release archives are generated using scripts/package-release.sh:

bash scripts/package-release.sh

Packaging Outputs in `target/dist/`:

nx9-wg-v1.0.0-linux-x86_64.tar.gz (Standard gzip archive)
nx9-wg-v1.0.0-linux-x86_64.tar.xz (High-compression XZ archive)
nx9-wg-v1.0.0-linux-x86_64.sha256 (Cryptographic SHA-256 checksums)

2. Release Documentation

The release documentation is versioned with the source tree. CHANGELOG.md records release-level changes, while docs/TESTING.md is the authoritative v1.0.0 testing and acceptance specification.

3. Release Archive Contents

Every release archive contains everything required for a standalone, offline production deployment:

nx9-wg-v1.0.0-linux-x86_64/
 ├── nx9-wg              (Native executable binary, mode 0755)
 ├── nx9-wg.service      (Hardened systemd unit file, mode 0644)
 ├── config.example.toml (Production configuration template, mode 0644)
 ├── install.sh          (Automated production installer, mode 0755)
 ├── uninstall.sh        (Safe uninstallation script, mode 0755)
 ├── README.md           (Primary project guide)
 ├── CHANGELOG.md        (Release history)
 ├── LICENSE-MIT         (MIT License text)
 ├── LICENSE-APACHE      (Apache 2.0 License text)
 └── docs/               (Complete offline documentation suite)

4. Standalone Verification Invariant

Release packages must function completely independently of the source repository. When extracted into an isolated clean directory (/tmp/nx9-release-verify...):

nx9-wg version outputs valid version, architecture, and platform strings.
nx9-wg --help lists all available subcommands.
nx9-wg init bootstraps the isolated SQLite database with WAL journals.
nx9-wg system health verifies database integrity.

5. Production Filesystem Layout

/usr/local/bin/nx9-wg        (0755 root:root - Binary)
/etc/nx9-wg/                 (0750 root:root - Configuration Directory)
 ├── config.toml             (0640 root:root - Main Configuration File)
 └── nx9-wg.env              (0600 root:root - Optional Environment Secrets)
/var/lib/nx9-wg/             (0700 root:root - State & Database Directory)
 ├── nx9-wg.db               (0600 root:root - Authoritative SQLite Database)
 ├── nx9-wg.db-wal           (0600 root:root - Write-Ahead Log Journal)
 ├── admin-password          (0600 root:root - Generated Initial Password)
 └── backups/                (0700 root:root - Database Backup Archives)
/var/log/nx9-wg/             (0750 root:root - Operational Logs)
/etc/systemd/system/
 └── nx9-wg.service          (0644 root:root - Systemd Service Unit)

6. Systemd Security Sandboxing

The production service unit (nx9-wg.service) enforces modern Linux security directives:

Capabilities: CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE & AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE.
Filesystem: ProtectSystem=strict, ProtectHome=true, PrivateTmp=true.
System Isolation: ProtectControlGroups=true, RestrictSUIDSGID=true, LockPersonality=true.
Socket Domains: RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK.
Directory Lifecycle: StateDirectory=nx9-wg, ConfigurationDirectory=nx9-wg, LogsDirectory=nx9-wg.

7. Upgrade and Rollback Sequence

Mandatory Upgrade Flow

Pre-Upgrade Backup: nx9-wg backup create --description "Pre-upgrade checkpoint"
Stop Service: sudo systemctl stop nx9-wg
Install Binary: sudo install -m 0755 nx9-wg /usr/local/bin/nx9-wg
Start Service: sudo systemctl start nx9-wg (Schema migrations run automatically upon startup)
Verify State: nx9-wg reconcile plan & nx9-wg system health

Rollback Flow

Stop Service: sudo systemctl stop nx9-wg
Revert Binary: sudo install -m 0755 nx9-wg-old /usr/local/bin/nx9-wg
Restore Database: nx9-wg backup restore <BACKUP_ID>
Start Service: sudo systemctl start nx9-wg

4.3 KiB Raw Blame History