cockpit-kata/quickstart.md

# Quick Start Guide — Cockpit Kata Containers

This guide walks you through installing and running Cockpit Kata Containers in both **standalone mode** (for development and demo) and **Cockpit module mode** (for production use on a real Kata host).

---

## Table of Contents

1. [Standalone Mode (No Kata Required)](#1-standalone-mode-no-kata-required)
2. [Cockpit Module Mode (Production)](#2-cockpit-module-mode-production)
3. [Verifying the Installation](#3-verifying-the-installation)
4. [Common Issues and Fixes](#4-common-issues-and-fixes)
5. [Next Steps](#5-next-steps)

---

## 1. Standalone Mode (No Kata Required)

Use standalone mode to explore the UI, develop features, or demo the module without a Kata Containers installation. All data comes from the mock layer — no real sandboxes, images, or configuration files are needed.

### Prerequisites

| Requirement | Version | Check Command |
|------------|---------|---------------|
| Node.js | 18+ | `node --version` |
| npm | 9+ | `npm --version` |
| (or) bun | 1+ | `bun --version` |

### Steps

```bash
# 1. Clone the repository
git clone <repo-url> cockpit-kata-containers
cd cockpit-kata-containers

# 2. Install dependencies
npm install

# 3. Start the development server
npm run dev
```

The app runs at **http://localhost:3000**. You should see the Kata Containers module with:

- 5 mock sandboxes (3 running, 1 stopped, 1 error)
- 4 pre-imported images (1 with validation errors)
- 4 runtime configurations (kata-qemu, kata-clh, kata-fc, kata-dragonball)
- Simulated metrics for running sandboxes

### What You Can Do

| Feature | How to Try It |
|---------|---------------|
| Browse sandboxes | Click "Sandboxes" in the sidebar — view the table, click a row for details |
| View sandbox detail | Click any sandbox name — see Overview, Metrics, Network, Console tabs |
| Import an image | Click "Import Image" — walk through the 4-step wizard with any `.tar.gz` or `.img` file |
| Export an image | Click "Export" — select a QCrows image, choose qcow2/ISO/PXE format, configure options, click Export |
| Inspect kernel | Click "Kernel" — view kernel config, boot params, hypervisor compatibility, and regenerate initrd |
| Push via PXE | Click "Import Image" → violet Radio button on any QCrows image → configure TFTP and push |
| Build a custom image | Click "Build Guide" — follow rootfs or initrd instructions with progress tracking |
| Edit configuration | Click "Configuration" — select a profile, click "Edit Config", modify TOML, save |
| View metrics | Click "Metrics" — see aggregate stats and per-sandbox breakdowns |

### Environment Variables (Optional)

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 3000 | Development server port |
| `KATA_IMAGE_DIR` | /tmp/kata-uploads | Directory for uploaded images (standalone mode) |

---

## 2. Cockpit Module Mode (Production)

Use Cockpit module mode on a host that runs Kata Containers. The module communicates with `kata-runtime`, `crictl`, `kata-monitor`, and the container runtime via Cockpit's bridge APIs.

### Prerequisites

| Requirement | Version | Install |
|------------|---------|---------|
| Cockpit | 286+ | OS package manager |
| kata-runtime | 2.5+ | See [Kata Containers docs](https://github.com/kata-containers/kata-containers#install) |
| containerd | 1.6+ | OS package manager |
| crictl | 1.25+ | OS package manager |
| KVM support | enabled | BIOS/UEFI + kernel module |
| Node.js | 18+ | For building the module only |
| npm | 9+ | For building the module only |

### Verify KVM Support

```bash
# Check if KVM is available
ls -la /dev/kvm

# Check if KVM kernel module is loaded
lsmod | grep kvm

# If not loaded, load it
sudo modprobe kvm_intel   # Intel CPUs
sudo modprobe kvm_amd     # AMD CPUs
```

### Verify Kata Installation

```bash
# Check kata-runtime version
kata-runtime --version

# Run the built-in host check
kata-runtime check
```

### Build and Install the Module

```bash
# 1. Enter the Cockpit module directory
cd cockpit-kata/

# 2. Install build dependencies
npm install

# 3. Build the production bundle
npm run build
# Output: dist/index.js, dist/index.js.map, dist/manifest.json

# 4. Install to Cockpit's package directory
sudo cp -r dist/ /usr/share/cockpit/kata/

# 5. Verify Cockpit sees the module
cockpit-bridge --packages | grep kata
# Expected output: kata
```

### Development Install (Symlink)

For iterative development, use a symlink instead of copying:

```bash
cd cockpit-kata/
npm install
npm run devel-install   # Creates ~/.local/share/cockpit/kata → $(pwd)
```

Changes are not live — you need to rebuild (`npm run build`) and refresh the browser. For auto-rebuild:

```bash
npm run watch            # Rebuilds on every file change
```

### Start kata-monitor (For Metrics)

The Metrics Dashboard requires `kata-monitor` running as a Prometheus endpoint:

```bash
# Start kata-monitor on the default port (8090)
sudo kata-monitor --listen-address 127.0.0.1:8090 &

# Verify it's running
curl -s http://127.0.0.1:8090/metrics | head -5
```

If you use a different address or port, update the CSP in `cockpit-kata/manifest.json`:

```json
"content-security-policy": "default-src 'self'; connect-src 'self' http://YOUR_ADDRESS:YOUR_PORT ws:; ..."
```

### Access Cockpit

```bash
# Start Cockpit (if not already running)
sudo systemctl enable --now cockpit.socket

# Open in browser
# https://<host-ip>:9090
```

Navigate to **Kata Containers** in the Cockpit sidebar.

---

## 3. Verifying the Installation

### Standalone Mode

1. Open http://localhost:3000
2. You should see the sidebar with 7 navigation items
3. Click "Sandboxes" — 5 mock sandboxes should appear
4. Click "Import Image" — the wizard should load with drag-and-drop zone
5. Click "Export" — QCrows image list with qcow2/ISO/PXE format selector
6. Click "Kernel" — kernel config viewer with hypervisor compatibility matrix
7. Click "Configuration" — 4 runtime profiles should be listed
8. Open browser DevTools (F12) — check for console errors (there should be none)

### Cockpit Module Mode

1. Open Cockpit at https://\<host\>:9090
2. Navigate to "Kata Containers" in the sidebar
3. The sandbox list should show real Kata sandboxes (if any are running)
4. Click "Configuration" — you should see the actual `configuration.toml` files from `/usr/share/defaults/kata-containers/`
5. Click "Edit Config" on a profile — modify a value, click Save, then verify the file was updated:
   ```bash
   cat /usr/share/defaults/kata-containers/configuration-qemu.toml
   ```

---

## 4. Common Issues and Fixes

### "cockpit-bridge --packages" doesn't show kata

**Cause:** The module files aren't in the right directory or Cockpit hasn't refreshed its cache.

```bash
# Verify the files are there
ls -la /usr/share/cockpit/kata/
# Should show: index.js, index.js.map, manifest.json

# Restart Cockpit to pick up new packages
sudo systemctl restart cockpit
```

### kata-runtime check fails

**Cause:** KVM not available, kata-runtime not installed, or wrong container runtime.

```bash
# Check KVM
ls /dev/kvm

# Check containerd CRI socket
ls /run/containerd/containerd.sock

# Check kata-runtime
which kata-runtime
kata-runtime --version

# Full diagnostic
kata-runtime check
```

### Metrics Dashboard shows "kata-monitor not running"

**Cause:** `kata-monitor` is not started or not on port 8090.

```bash
# Start it
sudo kata-monitor --listen-address 127.0.0.1:8090 &

# Or if it's on a different port, update the CSP in manifest.json
```

### Build fails with TypeScript errors

```bash
# Clear caches
rm -rf cockpit-kata/node_modules cockpit-kata/dist
cd cockpit-kata && npm install && npm run build
```

### Blank page in Cockpit

**Cause:** CSP blocking the module's scripts or network requests.

1. Open browser DevTools → Console
2. Look for CSP violation messages
3. Update `manifest.json`'s `content-security-policy` to allow the required origins

---

## 5. Next Steps

Once the module is running:

1. **Create a RuntimeClass** — Set up Kubernetes RuntimeClasses that reference your Kata configurations:
   ```bash
   kubectl apply -f - <<EOF
   apiVersion: node.k8s.io/v1
   kind: RuntimeClass
   metadata:
     name: kata-qemu
   handler: kata-qemu
   EOF
   ```

2. **Launch a Kata pod** — Deploy a pod using the RuntimeClass:
   ```bash
   kubectl run nginx-kata --image=nginx --runtimeclass=kata-qemu
   ```

3. **Import a custom image** — Use the Import Image wizard to bring in a rootfs or initrd with your application pre-installed.

4. **Build your own image** — Follow the Build Guide to create a custom Kata container image from scratch.

5. **Configure runtime settings** — Use the Configuration view to tune vCPU, memory, and boot parameters per VMM profile.

6. **Export for deployment** — Use the Export view to convert a QCrows image to qcow2 (QEMU VM), ISO (live USB), or PXE (network boot).

7. **Install QCrows CLI tools** — The automated installer deploys five CLI tools to `/usr/local/bin/`:
   ```bash
   qcrows-pack      # Create .qcrows archives
   qcrows-verify    # Verify .qcrows integrity
   qcrows-inspect   # Read .qcrows metadata
   qcrows-export    # Export to qcow2, ISO, or PXE
   qcrows-initrd-regen  # Regenerate initrd (env-aware)
   ```