# Testing NaxOS on macOS

This guide provides step-by-step instructions for testing and running the complete **NaxOS** appliance on macOS. It covers full live virtual machine testing with QEMU, rapid local frontend/API development, and headless automated verification.

---

## Testing Methods Overview

| Method | Target Use Case | Requirements |
| :--- | :--- | :--- |
| **Method 1: Full Live QEMU VM** | Complete appliance test: Linux 6.18 kernel, real OpenZFS pool `tank`, live `naxos-api` daemon, and `naxos-ui` web interface. | `qemu-system-x86_64` (Homebrew or Nix) |
| **Method 2: Local UI / API Dev** | Rapid UI development, styling iteration, and component testing on macOS without a VM. | Node.js 20+, npm |
| **Method 3: Headless Verification** | Automated end-to-end browser capture and visual validation. | Python 3 + Playwright or Chromium |

---

## Method 1: Full Appliance VM Testing via QEMU

This method boots the actual NaxOS NixOS 26.05 operating system with Linux kernel 6.18, creates a virtual target disk, provisions a real OpenZFS pool (`tank`), and runs the full API daemon and Web UI with port forwarding to macOS.

### 1. Prerequisites

Install QEMU on macOS using Homebrew (or via Nix):

```bash
# Using Homebrew
brew install qemu

# Or if you use Nix on macOS:
nix-shell -p qemu
```

Verify that `qemu-system-x86_64` is available:
```bash
qemu-system-x86_64 --version
```

> [!NOTE]
> **Apple Silicon (M1/M2/M3/M4) Note**: When running `qemu-system-x86_64` on Apple Silicon Macs, QEMU uses TCG (Tiny Code Generator) software emulation. Because it is emulating x86_64 on ARM64, boot times will take approximately 15–30 seconds.

---

### 2. Download the NaxOS Installation Media

Download the official bootable ISO from the Gitea package registry:

```bash
curl -fSL -o /tmp/naxos-installer.iso \
  "https://git.lholz.de/api/packages/naxos/generic/naxos-installer-iso/1.0.0/naxos-installer-x86_64-linux.iso"
```

---

### 3. Prepare Boot Artifacts & Virtual Drive

Extract the direct-boot kernel and initrd from the ISO (or boot directly from the ISO cdrom):

```bash
# Create a 20 GB QCOW2 virtual drive for OpenZFS testing
qemu-img create -f qcow2 /tmp/naxos-target-disk.qcow2 20G

# Mount or extract the ISO to retrieve the kernel and initrd
mkdir -p /tmp/naxos-iso-mnt /tmp/naxos-boot
hdiutil attach -nobrowse -readonly -mountpoint /tmp/naxos-iso-mnt /tmp/naxos-installer.iso
cp -R /tmp/naxos-iso-mnt/boot /tmp/naxos-boot/
hdiutil detach /tmp/naxos-iso-mnt
```

Find the extracted kernel and initrd paths:
```bash
KERNEL=$(find /tmp/naxos-boot -name bzImage | head -n 1)
INITRD=$(find /tmp/naxos-boot -name initrd | head -n 1)
echo "Kernel: $KERNEL"
echo "Initrd: $INITRD"
```

---

### 4. Launch the NaxOS Virtual Appliance

Start QEMU with:
- **RAM**: 2048 MB (2 GB)
- **CPU**: 2 cores (`-smp 2`)
- **Storage**: VirtIO disk attached to `/tmp/naxos-target-disk.qcow2` (appears as `/dev/vda` in the VM)
- **Networking**: User-mode networking with port forwarding:
  - Host port `18080` -> VM port `80` (NaxOS Web UI)
  - Host port `18443` -> VM port `8443` (NaxOS HTTPS / API)
- **Serial Console**: Stdio redirected to your terminal for real-time kernel and shell access.

```bash
qemu-system-x86_64 \
  -m 2048 \
  -smp 2 \
  -kernel "$KERNEL" \
  -initrd "$INITRD" \
  -append "init=/nix/store/*-nixos-system-nixos-*/init console=ttyS0,115200n8 loglevel=6" \
  -drive file=/tmp/naxos-target-disk.qcow2,if=virtio,format=qcow2 \
  -net nic,model=virtio \
  -net user,hostfwd=tcp::18443-:8443,hostfwd=tcp::18080-:80 \
  -nographic
```

Once booted, press **Enter** to get the root prompt:
```text
<<< Welcome to NixOS 26.05! >>>

[root@nixos:~]#
```

---

### 5. Initialize the OpenZFS Storage Pool in the VM

Inside the VM terminal, create the real OpenZFS pool `tank` on the virtual drive `/dev/vda`:

```bash
# Create OpenZFS pool
zpool create tank /dev/vda -f

# Create standard appliance datasets
zfs create tank/media
zfs create tank/backup
zfs create tank/container

# Verify pool health and status
zpool status
zpool list
zfs list
```

You should see:
```text
NAME             SIZE  ALLOC   FREE  CKPOINT  EXPANDSZ   FRAG    CAP  DEDUP    HEALTH  ALTROOT
tank            19.5G   832K  19.5G        -         -     0%     0%  1.00x    ONLINE  -
```

---

### 6. Verify Real System Metrics & Declarative Rebuild

The NaxOS Management Daemon (`naxos-api`) queries real kernel interfaces rather than mocked data:
- **ZFS ARC Cache**: `/proc/spl/kstat/zfs/arcstats`
- **Uptime**: `/proc/uptime`
- **Memory**: `os.totalmem()` and `os.freemem()`
- **Disk I/O**: `/proc/diskstats`
- **Journal Logs**: Real `journalctl -n 100 -o json --no-pager`

Test the API daemon endpoints from inside the VM or from macOS:

```bash
# Check system metrics from your Mac:
curl http://localhost:18443/api/v1/system/metrics

# Check real ZFS pools:
curl http://localhost:18443/api/v1/storage/pools

# Check active system services:
curl http://localhost:18443/api/v1/system/services
```

#### Testing "Apply Changes" (Live SSE Stream)
Trigger a declarative system rebuild from macOS:
```bash
curl -N -X POST http://localhost:18443/api/v1/system/rebuild
```
You will receive real Server-Sent Events (SSE) streaming live steps:
1. `validating` - Synthesizing declarative NixOS configuration.
2. `building` - Executing `/run/current-system/sw/bin/nixos-rebuild dry-activate`.
3. `reloading` - Applying dataset quotas and reloading Samba shares.
4. `completed` - Generation activated successfully.

---

### 7. Accessing the Web Dashboard

Open your web browser on macOS and navigate to:
```text
http://localhost:18080
```

You will see:
1. **Glassmorphism Appliance Dashboard**: Live storage capacity, real ARC hit ratio (100%), ARC cache size, CPU and memory gauges.
2. **Storage Management**: Visual hierarchy of pool `tank`, datasets (`media`, `backup`, `container`), and snapshots.
3. **App Store**: Curated 1-click catalog (Immich, Jellyfin, Nextcloud, Vaultwarden).
4. **Apply Changes Modal**: Interactive rebuild viewer streaming real systemd activation logs.

---

### 8. Clean VM Shutdown

To cleanly unmount OpenZFS datasets, export the storage pool, and power down the virtual machine, execute inside the VM console:

```bash
poweroff
```
Or press `Ctrl+A` then `X` to exit QEMU immediately.

---

## Method 2: Local UI & API Rapid Development

To develop or preview the Web UI directly on macOS without launching QEMU:

### 1. Build and Run the Web UI

```bash
cd naxos-ui

# Install dependencies
npm install

# Start Vite development server
npm run dev
```

Open `http://localhost:5173` in your browser.

### 2. Previewing the Production SPA Build

```bash
cd naxos-ui
npm run build
npm run preview -- --port 3000
```
Open `http://localhost:3000` to inspect the production asset bundle.

### 3. Running the Management Daemon Locally (Mock Fallback)

If running `naxos-api` on macOS outside of Linux, it automatically falls back gracefully when Linux-specific paths (`/proc/spl/kstat/zfs/arcstats`, `zpool`) are unavailable:

```bash
cd naxos-api
npm install
npm run build
npm start
```
The API daemon listens on `http://localhost:8088`.

---

## Method 3: Headless Automated Browser Verification

To run headless end-to-end tests or re-generate screenshots automatically:

```bash
# Using Python Playwright
python3 -m pip install playwright
python3 -m playwright install chromium

# Run headless screenshot verification
python3 - << 'EOF'
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page(viewport={"width": 1440, "height": 900})
    page.goto("http://localhost:18080")
    page.wait_for_selector("text=System Healthy")
    page.screenshot(path="test-overview.png")
    print("Screenshot captured successfully!")
    browser.close()
EOF
```

---

## Troubleshooting & FAQ

### Port `18080` or `18443` is already in use
Check which process is listening on the port:
```bash
lsof -i :18080
lsof -i :18443
```
Kill the stale process or change the `-net user,hostfwd=tcp::18080-:80` parameter in the QEMU launch command to an alternate port (e.g. `hostfwd=tcp::28080-:80`).

### Strict MIME Type Errors (`Failed to load module script`)
Browsers enforce strict MIME checking for ES modules (`Content-Type: text/javascript; charset=utf-8`). If serving files via Python or custom static servers, ensure MIME types are explicitly configured:
```python
import mimetypes
mimetypes.add_type('application/javascript', '.js')
mimetypes.add_type('text/css', '.css')
```
The standard `naxos-api` and production `nginx` containers already include appropriate MIME headers out of the box.