feat: complete nx9-wg v0.8.0 platform

2026-08-17 14:25:45 +05:30
1 parent c75e5c4e71
commit c8a9b7cde6
@@ -0,0 +1,95 @@
+# 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`](file:///home/sunil/Programs/nx9-wg/scripts/package-release.sh):
+
+```bash
+bash scripts/package-release.sh
+```
+
+### Packaging Outputs in `target/dist/`:
+- `nx9-wg-v0.8.0-linux-x86_64.tar.gz` (Standard gzip archive)
+- `nx9-wg-v0.8.0-linux-x86_64.tar.xz` (High-compression XZ archive)
+- `nx9-wg-v0.8.0-linux-x86_64.sha256` (Cryptographic SHA-256 checksums)
+
+---
+
+## 2. Release Archive Contents
+
+Every release archive contains everything required for a standalone, offline production deployment:
+
+```
+nx9-wg-v0.8.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)
+ ├── LICENSE-MIT         (MIT License text)
+ ├── LICENSE-APACHE      (Apache 2.0 License text)
+ └── docs/               (Complete offline documentation suite)
+```
+
+---
+
+## 3. 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.
+
+---
+
+## 4. 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)
+```
+
+---
+
+## 5. 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`.
+
+---
+
+## 6. Upgrade and Rollback Sequence
+
+### Mandatory Upgrade Flow
+1. **Pre-Upgrade Backup**: `nx9-wg backup create --description "Pre-upgrade checkpoint"`
+2. **Stop Service**: `sudo systemctl stop nx9-wg`
+3. **Install Binary**: `sudo install -m 0755 nx9-wg /usr/local/bin/nx9-wg`
+4. **Start Service**: `sudo systemctl start nx9-wg` (Schema migrations run automatically upon startup)
+5. **Verify State**: `nx9-wg reconcile plan` & `nx9-wg system health`
+
+### Rollback Flow
+1. **Stop Service**: `sudo systemctl stop nx9-wg`
+2. **Revert Binary**: `sudo install -m 0755 nx9-wg-old /usr/local/bin/nx9-wg`
+3. **Restore Database**: `nx9-wg backup restore <BACKUP_ID>`
+4. **Start Service**: `sudo systemctl start nx9-wg`