SOP-005 — Nova-Alpha Desktop Build & Recovery

1. Purpose

This Standard Operating Procedure documents the build, configuration, and recovery procedures for Nova-Alpha (hostname: Trunks), the primary on-prem host for Atlantis ITS infrastructure prior to VPS migration.

Nova-Alpha runs a hybrid architecture with services distributed across both Windows (host OS) and WSL2 Ubuntu (Linux subsystem). This document is the single source of truth for:

• Initial build and provisioning steps
• Ongoing service management
• Recovery after power loss, reboot, or system failure
• Verification and testing procedures

2. Scope

In scope:

• Windows 11 host OS configuration
• WSL2 Ubuntu subsystem setup
• Node.js / PM2 ecosystem (WSL side)
• .NET / C# hardware API (Windows side)
• Cross-ecosystem networking (WSL ↔ Windows bridge)
• Atlantis OPS Command Center deployment
• Auto-start and persistence configuration

Out of scope:

• VPS deployment (see forthcoming SOP-005)
• Docker container orchestration beyond basic install
• Production SaaS platform deployment
• Backup procedures (see SOP-003)

3. Machine Identity

4. Architecture Overview

Nova-Alpha operates a Dual Ignition Architecture — two parallel service ecosystems running on the same physical machine with different lifecycle management:

┌─────────────────────────────────────────────────┐
│  WINDOWS SIDE (Trunks host OS)                  │
│                                                 │
│  • Nova Hardware API (C# / .NET)               │
│    - LibreHardwareMonitor integration          │
│    - Port 5002                                  │
│  • Future: Immich, game/media servers          │
│                                                 │
│  Lifecycle: Windows Services / Task Scheduler  │
│  Reference: HT-014                              │
└─────────────────────────────────────────────────┘
                       ↑↓
              (172.26.x.x bridge)
                       ↑↓
┌─────────────────────────────────────────────────┐
│  WSL / UBUNTU SIDE                              │
│                                                 │
│  • Atlantis OPS Command Center (Next.js)       │
│    - Port 3000                                  │
│  • Discord bots (Python, future)               │
│  • n8n automation (future)                      │
│  • Kali offensive tools (future, isolated)     │
│                                                 │
│  Lifecycle: PM2                                 │
│  Reference: HT-013                              │
└─────────────────────────────────────────────────┘

Rationale for hybrid design:

1. Hardware access (temperature sensors, GPU load) requires Windows-native APIs. LibreHardwareMonitor cannot run under WSL.
2. Node.js and Python development is faster and cleaner in Linux.
3. Future VPS deployment will mirror the WSL-side stack, making services portable.
4. Security isolation — offensive tools (Kali) stay sandboxed in WSL, never touching Windows services.

5. Prerequisites

Before beginning the build, confirm:

• Windows 11 is installed and fully updated
• Administrator access is available
• Internet connectivity is stable
• GitHub account is accessible for SSH key registration
• Forgejo credentials are available (when Forgejo instance is deployed)

6. Windows Side Build

6.1 System Updates

Run first to ensure host stability.

1. Windows Update — Settings → Windows Update → Check for updates. Install all pending updates and reboot.
2. GPU drivers — Install the latest from NVIDIA, AMD, or Intel depending on installed card.
3. Chipset / LAN / Wi-Fi drivers — Typically handled by Windows Update. For gaps, check the motherboard manufacturer's support page (ASRock, ASUS, MSI, etc.).

6.2 Install .NET SDK

The Nova Hardware API requires the .NET 8 SDK (or current LTS).

From PowerShell (Administrator):

winget install --id Microsoft.DotNet.SDK.8 -e

Verify:

dotnet --version

6.3 Install Git for Windows

From PowerShell:

winget install --id Git.Git -e --source winget

Verify:

git --version

Configure identity:

git config --global user.name "Golboni"
git config --global user.email "<your-email>"

6.4 Deploy Nova Hardware API

Source location:

C:\Users\Shane\Desktop\nova-hardware-api

Dependencies (referenced in project file):

• LibreHardwareMonitor (NuGet)
• ASP.NET Core minimal API

Manual start (for testing):

cd C:\Users\Shane\Desktop\nova-hardware-api
dotnet run

The API binds to http://0.0.0.0:5002.

Endpoints:

Verification from Windows:

curl http://localhost:5002/api/hardware

Expected response includes ok: true, machine: "Nova-Alpha", and telemetry values.

6.5 Windows Auto-Start for Hardware API

See HT-014 — Windows Service Management for production-grade setup using NSSM or native Windows Services.

Interim solution (Startup .bat):

Create file at:

C:\Users\Shane\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\nova-hardware-api.bat

Contents:

@echo off
cd /d C:\Users\Shane\Desktop\nova-hardware-api
start "" /B dotnet run

This launches the API silently when Shane logs into Windows.

7. WSL Side Build

7.1 Enable WSL2 + Ubuntu

From PowerShell (Administrator):

wsl --install -d Ubuntu

Reboot when prompted. On first launch, set the Linux user as shane and configure a password.

7.2 Configure .wslconfig

Create or edit C:\Users\Shane\.wslconfig:

[wsl2]
memory=4GB
swap=2GB
processors=4

Note: Bump memory=4GB to memory=8GB when Ollama / Llama 8B is deployed (see Nova Phase 1 plan).

Apply:

wsl --shutdown

Then reopen Ubuntu.

7.3 Base Package Installation

Inside Ubuntu:

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git curl wget unzip \
                    python3 python3-pip python3-venv python3-dev

7.4 Install Node.js (LTS)

Using NodeSource for cleaner upgrades than Ubuntu's default repo:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

Verify:

node -v
npm -v

7.5 Install PNPM

npm install -g pnpm

7.6 Install PM2

sudo npm install -g pm2

See HT-013 — PM2 Process Manager for complete PM2 reference.

7.7 Install Docker (Optional, For Future Phases)

sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

sudo usermod -aG docker $USER

Restart WSL to apply group change:

wsl --shutdown

Verify after restart:

docker run hello-world

7.8 Generate SSH Keys (GitHub + Forgejo)

Generate separate keys for each Git provider:

ssh-keygen -t ed25519 -C "shane@github" -f ~/.ssh/id_github
ssh-keygen -t ed25519 -C "shane@forgejo" -f ~/.ssh/id_forgejo

Create ~/.ssh/config for routing:

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_github

Host forgejo.atlantisits.ai
    HostName forgejo.atlantisits.ai
    User git
    IdentityFile ~/.ssh/id_forgejo

Register public keys:

cat ~/.ssh/id_github.pub
# paste into GitHub → Settings → SSH and GPG Keys

cat ~/.ssh/id_forgejo.pub
# paste into Forgejo → User Settings → SSH Keys (when deployed)

Configure Git identity (WSL side):

git config --global user.name "Golboni"
git config --global user.email "<your-email>"

7.9 Create Nova Workspace

mkdir -p ~/nova/{agents,logs,services,ui}
cd ~/nova

Workspace structure:

~/nova/
├── agents/          # Discord bots and AI agent scripts
├── atlantis-ops/    # Command Center dashboard (cloned from GitHub)
├── logs/            # Centralized logging
├── services/        # Background services (n8n, NTFY, etc.)
└── ui/              # Additional UI projects

Expected future additions:

~/nova/
├── security/        # Kali tools, red/blue team scripts
├── brain/           # Ollama models, RAG database, memory files
└── forge/           # Local Forgejo mirror/cache

See HT-012 — Nova Workspace Structure for complete taxonomy.

7.10 Create Python Virtual Environment

python3 -m venv ~/nova-env
source ~/nova-env/bin/activate
pip install --upgrade pip
deactivate

This sandbox is reused for Python-based agents (Discord bots, automation scripts).

7.11 Install VS Code WSL Extension

On Windows:

1. Install Visual Studio Code
2. Install the "WSL" extension by Microsoft
3. From WSL terminal: cd ~/nova && code .

VS Code opens with full WSL integration.

8. Deploy Atlantis OPS Command Center

The OPS dashboard is the primary UI for Nova-Alpha telemetry and service orchestration.

8.1 Clone Repository

cd ~/nova
git clone git@github.com:Golboni/atlantis-ops.git

8.2 Install Dependencies

cd ~/nova/atlantis-ops
npm install

8.3 Configure Environment

Review .env.local for:

• Hardware API endpoint (default: http://172.26.208.1:5002)
• Weather API key (if used)
• Port configuration (default: 3000)

8.4 Start Under PM2

cd ~/nova/atlantis-ops
pm2 start npm --name atlantis-ops -- run start
pm2 save

8.5 Verify

Open a browser to http://localhost:3000. The dashboard should display:

• Mission Status card
• Local Weather card
• Nova-Alpha telemetry card (pulling from hardware API)
• Local Apps card

If telemetry shows -- or errors, verify the hardware API is running on the Windows side (see Section 6.4) and that the WSL-to-Windows bridge is functioning (see Section 9).

9. Cross-Ecosystem Bridge (WSL ↔ Windows)

WSL communicates with the Windows host over a virtual network. The Windows host IP (as seen from WSL) changes occasionally but typically falls within the 172.x.x.x range.

9.1 Discover Windows Host IP From WSL

ip route show | grep -i default | awk '{ print $3}'

Example output:

172.26.208.1

9.2 Test Bridge Connectivity

From WSL:

curl http://172.26.208.1:5002/api/hardware

Successful response confirms the bridge is working and the hardware API is reachable.

9.3 Windows Firewall Considerations

If connectivity fails, Windows Defender Firewall may be blocking port 5002. Add an inbound rule:

1. Windows Defender Firewall → Advanced Settings
2. Inbound Rules → New Rule
3. Type: Port → TCP, Specific port: 5002
4. Action: Allow the connection
5. Profile: Private (do NOT expose on Public networks)
6. Name: "Nova Hardware API (WSL bridge)"

See HT-015 — WSL ↔ Windows Bridge for deeper networking details.

10. Operational Command Reference

10.1 Hardware API (Windows side)

Start manually:

cd C:\Users\Shane\Desktop\nova-hardware-api
dotnet run

Test:

curl http://localhost:5002/api/hardware

Stop: Ctrl + C in the running terminal, or kill the dotnet process in Task Manager.

10.2 Atlantis OPS (WSL side)

Start / restart:

pm2 start atlantis-ops            # if not started
pm2 restart atlantis-ops          # if already started

Status:

pm2 list
pm2 show atlantis-ops

Logs:

pm2 logs atlantis-ops --lines 100

Stop:

pm2 stop atlantis-ops

10.3 WSL Control (from Windows)

Start WSL:

wsl

Shutdown WSL (force all distros to stop):

wsl --shutdown

List distros:

wsl --list --verbose

11. Auto-Start and Persistence

The goal: after any reboot or power loss, Nova-Alpha returns to full operational state with zero manual intervention.

11.1 Windows Side — Hardware API Auto-Start

Use the Startup .bat method from Section 6.5, or upgrade to a Windows Service per HT-014.

11.2 WSL Side — PM2 Persistence

Inside WSL:

pm2 startup systemd
# copy and run the sudo command it prints

pm2 save

See HT-013 — PM2 Process Manager → Persistence section for full details.

11.3 WSL Auto-Start on Windows Boot

Create a Task Scheduler entry:

1. Press Win + R, type taskschd.msc, press Enter
2. Create Basic Task → Name: Start WSL on Boot
3. Trigger: When I log on
4. Action: Start a program
5. Program: wsl.exe
6. Arguments: -d Ubuntu -u shane

This starts WSL after login. Once WSL starts, systemd + PM2 resurrect all saved processes automatically.

12. Recovery Procedures

12.1 Power Loss Recovery (Standard)

Scenario: Unexpected power loss or hard reboot. Services may or may not come back automatically depending on auto-start configuration.

Steps:

1. Power on machine and log into Windows as Shane
2. Open PowerShell and verify hardware API:

   curl http://localhost:5002/api/hardware
   

3. Open WSL:

   wsl
   

4. Verify PM2 state:

   pm2 list
   

5. If atlantis-ops is missing or stopped:

   pm2 resurrect
   

6. If resurrect fails, start manually:

   cd ~/nova/atlantis-ops
   pm2 start npm --name atlantis-ops -- run start
   pm2 save
   

7. Verify dashboard at http://localhost:3000
8. Document any deviation in the Runbook log (future: ~/nova/logs/runbook.log)

12.2 Hardware API Not Responding

Symptoms: Dashboard telemetry shows -- or errors. WSL curl to 172.26.x.x:5002 times out.

Steps:

1. Check if the process is running on Windows:

   Get-Process -Name dotnet
   

2. If missing, start manually:

   cd C:\Users\Shane\Desktop\nova-hardware-api
   dotnet run
   

3. Test from Windows first:

   curl http://localhost:5002/api/hardware
   

4. If Windows-side works but WSL-side fails, re-check the host IP:

   ip route show | grep -i default | awk '{ print $3}'
   

5. Update .env.local in atlantis-ops if IP changed, restart PM2:

   pm2 restart atlantis-ops
   

6. Check Windows Defender Firewall rule for port 5002.

12.3 OPS Dashboard Crash Loop

Symptoms: pm2 list shows the restart counter (↺) climbing rapidly.

Steps:

1. Stop the loop:

   pm2 stop atlantis-ops
   

2. Check logs for the root cause:

   pm2 logs atlantis-ops --lines 200
   

3. Common causes:
4. Port 3000 already in use by another process
5. Missing npm dependencies (run npm install)
6. Corrupted .env.local or missing env vars
7. Git pull introduced breaking changes (check git log recent commits)
8. Fix underlying issue, then:

   pm2 restart atlantis-ops
   

12.4 Full Rebuild From Scratch

If Nova-Alpha is unrecoverable, re-execute this SOP starting at Section 6. Expected rebuild time: 2–3 hours with all credentials on hand.

13. Verification Checklist

After initial build or recovery, confirm all items:

• [ ] Windows is updated and stable
• [ ] GPU drivers current
• [ ] .NET SDK installed (dotnet --version)
• [ ] Git for Windows installed and identity configured
• [ ] Nova Hardware API responds on http://localhost:5002/api/hardware
• [ ] Hardware API auto-starts on Windows login (startup .bat or service)
• [ ] WSL2 Ubuntu installed and launches cleanly
• [ ] .wslconfig configured with target memory/processors
• [ ] Node.js LTS installed (node -v)
• [ ] PNPM installed (pnpm -v)
• [ ] PM2 installed (pm2 --version)
• [ ] SSH keys generated (GitHub + Forgejo slots)
• [ ] Nova workspace created at ~/nova/
• [ ] Python venv at ~/nova-env/
• [ ] atlantis-ops cloned to ~/nova/atlantis-ops/
• [ ] atlantis-ops starts under PM2
• [ ] Dashboard loads at http://localhost:3000
• [ ] Telemetry populates from hardware API
• [ ] PM2 persistence configured (pm2 startup + pm2 save)
• [ ] WSL Task Scheduler entry created for boot auto-start
• [ ] Reboot test performed — all services return automatically

14. Related Documents

• HT-011 — Nova-Alpha Quick Access (Terminal profiles, PowerShell aliases)
• HT-012 — Nova Workspace Structure (folder taxonomy, Git/SSH pattern)
• HT-013 — PM2 Process Manager
• HT-014 — Windows Service Management (for Hardware API production setup)
• HT-015 — WSL ↔ Windows Bridge (cross-ecosystem networking)
• SOP-001 — PowerShell 7 Upgrade
• SOP-003 — Pre-Upgrade Backup and Rollback Procedure
• INC-001 — AAL v2 Upgrade Failure

15. Known Issues & Watch Items

16. Revision History

17. Approval

End of SOP-005 — Nova-Alpha Desktop Build & Recovery