Installation & Deployment Guide

This guide describes the installation, configuration, and system service setup of Cockpit. It covers both single-instance deployments and high-availability clustered architectures.

---

Deployment Topologies

Choose the deployment topology that aligns with your infrastructure requirements:

1. Single-Instance Deployment

Suitable for small environments managing fewer than 20 Vapor hypervisors. A single Cockpit application gateway process connects directly to a standalone PostgreSQL database server. This architecture is straightforward to configure but lacks fault tolerance.

2. Multi-Instance (High-Availability Clustered) Deployment

Recommended for production environments where downtime must be minimized. Multiple active-active Cockpit instances run concurrently behind a Layer 7 load balancer (such as HAProxy or NGINX). The instances coordinate state using a shared, clustered PostgreSQL database (e.g., managed via Patroni) and synchronize events in real-time using PostgreSQL pg_notify channels.

---

Step 1: Database Initialization

Cockpit requires a PostgreSQL database (version 15 or higher) to store configuration data, audit trails, and inventory metadata.

The database schema utilizes the uuid-ossp extension to generate RFC 4122 compliant universally unique identifiers (UUIDs) for primary keys across all cluster resources (including virtual machines, user records, and network interfaces).

Database Script

Log in to your PostgreSQL console and execute the following configuration commands:

-- 1. Create a new target database
CREATE DATABASE cockpit_db;

-- 2. Create the system service account with a secure password
CREATE USER cockpit_user WITH PASSWORD 'securepassword';

-- 3. Grant schema privileges to the service account
GRANT ALL PRIVILEGES ON DATABASE cockpit_db TO cockpit_user;

-- 4. Connect to the newly created database
\c cockpit_db

-- 5. Enable the UUID generation extension
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

---

Step 2: System Installation

Cockpit can be deployed either as a compiled system binary or inside a container engine (Docker or Podman).

Option A: Standalone Binary Installation

1. Obtain the compiled cockpit binary matching your target architecture.
2. Relocate the binary to the system binary directory: /usr/local/bin/cockpit.
3. Configure executable permissions: chmod +x /usr/local/bin/cockpit.
4. Create the system configuration directory: mkdir -p /etc/cockpit.

Option B: Containerized Deployment

To build and run the Cockpit service as a container, use the following commands:

# 1. Compile the container image from the project root
docker build -t awanio/cockpit:latest -f Containerfile .

# 2. Run the container container with the PostgreSQL connection string
docker run -d \
  -p 7771:7771 \
  --name cockpit-server \
  -v /etc/cockpit:/etc/cockpit \
  -e DATABASE_URL="postgres://cockpit_user:securepassword@db-host:5432/cockpit_db?sslmode=disable" \
  awanio/cockpit:latest

---

Step 3: Configuration (cockpit.conf)

Cockpit reads its runtime settings from /etc/cockpit/cockpit.conf. Below is an example configuration file:

# --- Connection & HTTP Gateway Settings ---
PORT = 7771
BIND_ADDRESS = "0.0.0.0"
SSL_CERT = "/etc/cockpit/certs/server.crt" # Path to local TLS certificate
SSL_KEY = "/etc/cockpit/certs/server.key"  # Path to local TLS private key

# --- Database Integration ---
# PostgreSQL connection URL and connection pool configuration
DATABASE_URL = "postgres://cockpit_user:securepassword@localhost:5432/cockpit_db?sslmode=disable"
DB_MAX_IDLE_CONNS = 10
DB_MAX_OPEN_CONNS = 100

# --- JWT Authentication Security ---
# Cryptographic signing key for JSON Web Tokens
JWT_SECRET = "supersecretjsonwebtokenkeyfordevelopment"
JWT_EXPIRATION_HOURS = 24

# --- Downstream Metrics & Telemetry ---
# Telemetry sweep and health check properties (in seconds)
COLLECTOR_HEALTH_CHECK_INTERVAL = 10
VAPOR_WS_TIMEOUT_SECONDS = 120

---

Step 4: Systemd Service Configuration

When running Cockpit as a standalone binary, configure systemd to manage the lifecycle of the daemon:

Create the service configuration file /etc/systemd/system/cockpit.service containing:

[Unit]
Description=Cockpit Multi-Host Vapor Manager
After=network.target postgresql.service

[Service]
Type=simple
User=cockpit
WorkingDirectory=/var/lib/cockpit
ExecStart=/usr/local/bin/cockpit -config /etc/cockpit/cockpit.conf
Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Starting the Daemon

Execute the following commands to reload systemd, enable the service on boot, and start the daemon:

# 1. Reload the systemd manager configuration
systemctl daemon-reload

# 2. Enable the service and execute the start command
systemctl enable --now cockpit.service

# 3. Monitor system log outputs
journalctl -u cockpit.service -f