Getting Started with Cockpit

Cockpit serves as the centralized management gateway for the Vapor virtualization platform. This guide outlines the system architecture, communication flows, and system requirements necessary for deploying Cockpit.

---

Technical Terminology

Virtualization administration involves several core infrastructure components:

Terminology Reference

• Hypervisor: A physical host server running a virtualization kernel (KVM/QEMU) managed by a local agent (Vapor).
• REST API: A representational state transfer interface used by clients to execute administrative commands and fetch configuration states over HTTP.
• WebSocket: A full-duplex, persistent connection protocol used to push real-time events and telemetry updates from the server to clients with minimal overhead.
• PostgreSQL Advisory Lock: An application-defined database lock used to coordinate host management and prevent split-brain conflicts in multi-instance deployments.
• pg_notify: An asynchronous notification channel in PostgreSQL used to broadcast events across multiple active Cockpit instances.

---

Communication Architecture

Cockpit acts as the central gateway between administrators and the physical Vapor hypervisors. It implements a two-tier communication model:

1. Downstream (Cockpit-to-Vapor): Cockpit establishes secure connections to the local Vapor host agent on port 7770. This link is used to query hardware properties, fetch VM configurations, and stream real-time events.
2. Upstream (Client-to-Cockpit): Clients connect to the Cockpit API Gateway on port 7771 via HTTPS and WebSockets. The API Gateway authenticates users, verifies role privileges, and serves the unified console UI.

                  ┌────────────────────────────────┐
                  │          Cockpit Web UI        │
                  │       (Client Web Browser)     │
                  └──────────────┬─────────────────┘
                                 │
                                 ▼ HTTPS / WebSockets (Upstream Connection)
                  ┌────────────────────────────────┐
                  │      Cockpit API Gateway       │
                  │   (Central Brain / Coordinator)│
                  └──────────────┬─────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         ▼                       ▼                       ▼
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
 │   Vapor Host 1  │     │   Vapor Host 2  │     │   Vapor Host 3  │
 │  (TCP Port 7770)│     │  (TCP Port 7770)│     │  (TCP Port 7770)│
 └─────────────────┘     └─────────────────┘     └─────────────────┘

---

Core Architecture Components

The Cockpit architecture consists of several specialized backend services:

• Collector Service: A background daemon that maintains persistent connections to all registered Vapor host agents. It reconciles host states, processes telemetry samples, and updates the shared database.
• PostgreSQL Database: The shared configuration store. It holds user definitions, role mapping, host registration metadata, and system metrics.
• PostgreSQL Advisory Locks: Used in multi-instance setups to enforce mutual exclusion. Each Vapor host is locked by a single collector instance; if the active instance fails, a standby instance acquires the lock and assumes management of the host.
• WebSocket Event Hub: A real-time message broker. It consumes events generated by the Collector Service and broadcasts them to connected browsers. Multi-instance setups use PostgreSQL pg_notify to route messages across instances.

---

System Requirements

Ensure the deployment host meets the following hardware and software requirements before installing Cockpit:

Component	Minimum Specification	Recommended Specification	Rationale
CPU Cores	2 vCPUs	4+ vCPUs	Required to handle concurrent API requests and telemetry parsing.
System RAM	4 GB	8+ GB	Required to manage active WebSocket connection buffers and concurrent processes.
Storage	20 GB (SSD)	50+ GB	Stores database records, audit trails, and performance history.
Database	PostgreSQL 15 or later	Clustered PostgreSQL (Patroni)	Used for central state storage and transaction synchronization.
Network	1 Gbps	10 Gbps	Necessary for inter-instance synchronization and metrics streaming.
Vapor Nodes	Vapor 1.0.0 or later	Vapor with TLS configured	Target hypervisors managed by the Cockpit controller.