Server Commissioning

Commissioning is the process by which ServOS takes a “vanilla” Linux server and prepares it to host your applications. This process uses a lightweight agent that is automatically provisioned via SSH.

What happens during Commissioning?

When you click the Commission button, ServOS performs the following steps in sequence:

1. SSH Connection: ServOS establishes a secure SSH connection to the server using the provided IP and Private Key.
2. System Audit: ServOS checks the OS version (Ubuntu 22.04+ recommended) and architecture.
3. Dependency Installation:
   • Installs docker.io and docker-compose-v2.
   • Installs wireguard for the mesh network (falls back to userspace wireguard-go as a systemd unit when the kernel module is missing).
   • Installs nixpacks, so repository builds work without a Dockerfile.
4. Firewall: ServOS does not touch the host firewall. Open SSH (22/tcp), HTTP (80/tcp), HTTPS (443/tcp) and WireGuard (51820/udp) yourself — see Firewall Rules.
5. Infrastructure Setup:
   • Creates the servos-infra Docker network.
   • Deploys the Traefik Ingress Proxy.
   • Deploys the Docker Socket Proxy (for secure, restricted access to the Docker API).
6. Mesh Networking & Agent:
   • Creates a non-privileged system user and group named servos.
   • Installs the servos-agent binary and sets up a systemd service.
   • Generates WireGuard keys for the server.
   • Configures the WireGuard interface (wg0).
   • Starts the agent, which pulls the initial MeshState via HTTP.
7. Health Check: ServOS verifies that Docker is responsive and Traefik is reachable.

Troubleshooting Commissioning

Permission Denied (Public Key)

• Cause: The Ed25519 or ECDSA private key provided does not match any authorized keys on the server. RSA and DSA keys are intentionally unsupported.
• Fix: Ensure your public key is in /root/.ssh/authorized_keys (if using root) or the appropriate user’s folder.

Firewall Lockout

• Cause: You have an external firewall (AWS Security Group, etc.) that is blocking the ports ServOS is trying to use.
• Fix: Ensure ports 22, 80, 443, and 51820 are open in your cloud provider’s console.

Docker Installation Failure

• Cause: Existing package manager locks or broken repositories.
• Fix: Run apt-get update manually on the server to check for errors.

Post-Commissioning

Once a server is commissioned, it is marked as Ready. You can then:

• Link it to one or more Environments (in Advanced Mode).
• Deploy Services or Databases to it.
• View real-time Metrics (CPU, RAM, Disk).
• Access the SSH Terminal directly from the ServOS dashboard.