cockpit-kata/cockpit-kata/README.md

Cockpit Kata Containers Module — Build & Install

Quick Start

# Install dependencies
npm install

# Build for production
npm run build

# Install for local Cockpit development (symlinks to ~/.local/share/cockpit/kata)
npm run devel-install

# Watch for changes during development
npm run watch

Production Install

# Build
npm run build

# Copy the dist/ directory to the system Cockpit package directory
sudo cp -r dist/ /usr/share/cockpit/kata/

# Verify Cockpit sees the package
cockpit-bridge --packages | grep kata

Architecture

cockpit-kata/
├── manifest.json          # Cockpit package manifest (menu placement, CSP, version requirements)
├── webpack.config.js      # Build config — bundles React app into single JS file
├── package.json           # npm build scripts and dependencies
├── tsconfig.json          # TypeScript config
├── cockpit.d.ts           # Type declarations for cockpit.js APIs
├── src/
│   ├── index.tsx           # Entry point — mounts KataModule into DOM
│   ├── KataModule.tsx      # Main component (copied from Next.js prototype)
│   ├── backend/
│   │   ├── adapter.ts      # Backend adapter — selects cockpit vs mock mode
│   │   ├── cockpit-api.ts  # Real cockpit.spawn() / cockpit.http() / cockpit.file() calls
│   │   └── mock-api.ts     # Mock fallback for standalone development
│   ├── components/         # UI components (same as Next.js prototype)
│   └── types.ts            # Shared TypeScript interfaces
└── dist/                   # Build output — files Cockpit actually serves
    ├── index.js            # Bundled React app
    ├── index.js.map        # Source map for debugging
    └── manifest.json       # Copied from root

Backend Adapter Pattern

The module uses a two-mode backend:

1. Cockpit mode (production): cockpit.spawn() calls kata-runtime / kata-ctl / crictl, cockpit.http() talks to kata-monitor on 127.0.0.1:8090, cockpit.file() watches/edits configuration.toml

2. Mock mode (standalone dev): Same TypeScript interfaces, but backed by simulated data and delays. This is what the Next.js prototype uses.

The adapter in src/backend/adapter.ts auto-detects whether cockpit is available in the global scope and selects the appropriate implementation.

CSP Requirements

The manifest.json includes a content-security-policy that allows:

• connect-src 'self' http://127.0.0.1:8090 ws: — for kata-monitor HTTP and WebSocket
• style-src 'self' 'unsafe-inline' — for CSS-in-JS (React inline styles)
• img-src 'self' data: — for inline SVG icons and data URIs

If kata-monitor binds to a different address, update the CSP in manifest.json.

Integration with Cockpit Machines Module

The Kata module follows the same UX patterns as Cockpit's machines module:

• List view → detail view navigation
• Action dropdown menus (start/stop/restart/console)
• Breadcrumb-based navigation back to list
• Card-based summary stats at the top of list views

Key divergences from the machines module:

• Kata sandboxes are ephemeral (per-pod lifecycle), not persistent VMs
• Creation happens via Kubernetes RuntimeClass, not an in-module wizard
• Import is for rootfs/initrd images, not disk images
• Config is TOML, not libvirt XML
• Console is vsock-based text only, not VNC