Installation & Deployment Guide

This guide explains how to install and configure Cockpit on your servers, whether you want a simple single-server setup or a highly reliable clustered system.

---

Choosing Your Setup (Deployment Topologies)

Before installing, decide which setup style fits your business needs.

1. Single Instance (Standard Setup)

Perfect for smaller setups (managing under 20 physical Vapor servers). The Cockpit program runs on a single server, connected to a database.

• 💡 Analogy: Think of this like a food cart with one chef. The chef does everything: takes orders, cooks, and serves. It is simple to start and inexpensive. However, if the chef gets sick (the server crashes), the food cart has to close down.

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

Recommended for businesses that cannot afford any downtime. Multiple Cockpit servers run at the same time behind a Load Balancer (a traffic controller like HAProxy or Nginx that routes users to the active server).

• 💡 Analogy: Think of this like a large restaurant kitchen with a team of chefs. A host at the door guides guests to tables. If one chef steps out (one Cockpit server crashes), the other chefs keep cooking so the guests don't notice. They use a shared order book (Clustered PostgreSQL) and an intercom (pg_notify) to make sure they do not prepare the same dish twice.

---

Step 1: Database Setup

Cockpit requires a PostgreSQL database (version 15 or higher) to store its configuration, user accounts, and list of servers.

We also need to enable the uuid-ossp extension.

• Why? This extension is like a digital labeling machine. It automatically stamps a completely unique ID number (UUID) on every single virtual machine, user account, and network we create, ensuring they never get mixed up.

Initializing the Database:

Log into your PostgreSQL console and run the following database commands:

-- 1. Create a new database named "cockpit_db"
CREATE DATABASE cockpit_db;

-- 2. Create a database user named "cockpit_user" with a secure password
CREATE USER cockpit_user WITH PASSWORD 'securepassword';

-- 3. Give this user full permission to read and write to the database
GRANT ALL PRIVILEGES ON DATABASE cockpit_db TO cockpit_user;

-- 4. Connect to the database we just created
\c cockpit_db

-- 5. Install the unique label maker extension (UUID generator)
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

---

Step 2: Installing Cockpit

You can install Cockpit as a direct program (binary) or run it inside a container (Docker/Podman).

Option A: Running as a Direct Program (Binary)

1. Download the latest cockpit program file for your server.
2. Put the file in the systems folder: /usr/local/bin/cockpit.
3. Give it permission to run: chmod +x /usr/local/bin/cockpit.
4. Create a folder to hold settings: mkdir -p /etc/cockpit.

Option B: Running as a Container (Docker/Podman)

If you prefer containers, you can build and run Cockpit with these commands:

# 1. Build the container from the source files
docker build -t awanio/cockpit:latest -f Containerfile .

# 2. Run the container and link it to your database
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: Configuring Cockpit (cockpit.conf)

Cockpit reads its settings from a file named /etc/cockpit/cockpit.conf. Here is an example configuration file explained:

# --- Connection & Web Settings ---
PORT = 7771
BIND_ADDRESS = "0.0.0.0" # Listen for connections from any network address
SSL_CERT = "/etc/cockpit/certs/server.crt" # Path to secure HTTPS certificate
SSL_KEY = "/etc/cockpit/certs/server.key"  # Path to security key

# --- Database Connection ---
# Tells Cockpit how to log into the PostgreSQL database:
DATABASE_URL = "postgres://cockpit_user:securepassword@localhost:5432/cockpit_db?sslmode=disable"
DB_MAX_IDLE_CONNS = 10
DB_MAX_OPEN_CONNS = 100

# --- Login Token Security (JWT) ---
# A long, secret password that Cockpit uses to sign digital entry passes (tokens)
JWT_SECRET = "supersecretjsonwebtokenkeyfordevelopment"
JWT_EXPIRATION_HOURS = 24

# --- Manager Settings ---
# How often (in seconds) Cockpit checks if its connected Vapor hosts are still alive
COLLECTOR_HEALTH_CHECK_INTERVAL = 10
VAPOR_WS_TIMEOUT_SECONDS = 120

---

Step 4: Running Cockpit automatically (Systemd)

If you are running the binary directly, you should make sure Cockpit starts automatically when the server boots.

Create a file named /etc/systemd/system/cockpit.service and add the following lines:

[Unit]
Description=Cockpit Multi-Host Vapor Manager
After=network.target postgresql.service # Start only after the network and database are ready

[Service]
Type=simple
User=cockpit
WorkingDirectory=/var/lib/cockpit
ExecStart=/usr/local/bin/cockpit -config /etc/cockpit/cockpit.conf # Run Cockpit with our config file
Restart=always # If it crashes, start it back up automatically
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Enable and start the service:

Run these commands in your server terminal:

# 1. Tell the server to read the new service file
systemctl daemon-reload

# 2. Configure Cockpit to start automatically on boot and start it now
systemctl enable --now cockpit.service

# 3. Check the live server logs to make sure it running smoothly
journalctl -u cockpit.service -f