101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
# 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`](../scripts/package-release.sh):
|
|
|
|
```bash
|
|
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
|
|
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`
|