Getting Started with Cockpit

Cockpit acts as the central dashboard for all your virtual machines and servers. Before setting it up, it helps to understand how its parts talk to each other and what hardware you need.

---

Jargon Buster 📖

Virtualization comes with a lot of heavy technical words. Here is what they actually mean in plain English:

💡 Terms Explained

• Hypervisor: A physical computer that runs special software allowing it to host multiple virtual computers (Virtual Machines or VMs) at the same time.
• REST API: A web communication style. Think of it like a menu at a restaurant: your web browser or script orders a specific action (like "start VM #2"), and the server delivers it.
• WebSocket: A live, two-way connection. Instead of your browser asking the server every second "Is the backup done yet?" (which is called polling), the server keeps a line open and whispers updates the millisecond they happen.
• Advisory Lock: A digital agreement in the database that acts like a "talking stick" in a meeting. Only the server holding the stick is allowed to talk to a specific Vapor host, preventing other servers from interrupting or sending duplicate instructions.
• pg_notify: A built-in intercom system inside the database. When one Cockpit server receives an event (like a VM starting up), it uses this intercom to broadcast the news instantly to all other Cockpit servers.

---

How Cockpit Communicates (Architecture)

Cockpit sits in the middle between you (the administrator) and the physical computers running your virtual machines (Vapor hosts).

It uses a two-tier architecture (a two-layer structure):

1. Downstream (Cockpit to Vapor): Cockpit talks to the physical servers running Vapor. It connects to them to pull hardware info, check VM statuses, and receive live performance statistics.
2. Upstream (Client to Cockpit): Your web browser connects to Cockpit. Cockpit checks who you are (your login credentials), verifies what you are allowed to do (permissions), and shows you the combined view of all servers.

                  ┌────────────────────────────────┐
                  │          Cockpit Web UI        │
                  │     (What you see in browser)  │
                  └──────────────┬─────────────────┘
                                 │
                                 ▼ (REST / WebSockets - Live communication)
                  ┌────────────────────────────────┐
                  │      Cockpit API Gateway       │
                  │   (Central Brain / Coordinator)│
                  └──────────────┬─────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Vapor Host 1  │     │   Vapor Host 2  │     │   Vapor Host 3  │
│(Physical Server)│     │(Physical Server)│     │(Physical Server)│
└─────────────────┘     └─────────────────┘     └─────────────────┘

---

Core Infrastructure Components

Under the hood, Cockpit uses a few helper programs to keep everything in sync:

• The Collector Service: A background worker in Cockpit that acts like a manager. Its job is to keep in touch with the Vapor servers and write down what they are doing in Cockpit's database.
• The PostgreSQL Database: The central registry. It stores everything: which user accounts exist, who is allowed to click which buttons, and the list of physical servers.
• PostgreSQL Advisory Locks (Workload Sharing): If you run multiple Cockpit servers for reliability (called high availability), they might compete to talk to the same physical host. To prevent this, they compete for an "advisory lock" in the database. The winner manages the host; if that winner crashes, the lock is freed and another Cockpit server takes over immediately.
• WebSocket Event Hub (Real-time Broadcaster): When a virtual machine starts or stops, this hub broadcasts the event to your browser so you see the state change on your screen instantly. If you have multiple Cockpit servers, they use the pg_notify database intercom to make sure every admin sees the update, no matter which Cockpit server they are connected to.

---

System Requirements

Ensure your hardware meets these baseline requirements before installing Cockpit:

Component	Minimum Specification	Recommended Specification	Why does it need this?
CPU Cores	2 vCPUs	4+ vCPUs	To process incoming metrics and manage host connections.
System RAM	4 GB	8+ GB	To hold active WebSocket connections and run the background workers.
Storage	20 GB (SSD preferred)	50+ GB	Stores database records, audit trails, and logs.
Database	PostgreSQL 15 or later	Clustered PostgreSQL (Patroni)	Where all settings and status records are saved.
Network	1 Gbps NIC	10 Gbps dedicated network	Crucial for fast communications and transferring VMs between hosts.
Vapor Nodes	Vapor 1.0.0 or later	HTTPS configured with valid certs	The target physical servers you want Cockpit to manage.