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