Getting Started with ServOS

This guide will walk you through setting up ServOS and deploying your first application.

Prerequisites

• A Linux server with SSH access (Ubuntu 22.04+ recommended)
• Docker installed on your local machine (for building images)
• A domain name pointing to your server (for HTTPS)

Installation

1. Automated Installation (Recommended)

Run the installer to set up ServOS, systemd services, and configuration automatically:

curl -fsSL https://cdn.drmhse.com/servos/install.sh | bash

Or pin to a specific version:

curl -fsSL https://cdn.drmhse.com/servos/install.sh | bash -s -- --version v0.1.0

2. Manual Installation

If you prefer to install manually or need a specific platform (macOS/Windows/Linux), visit our Downloads Page or use the commands below:

# 1. Download the latest release
curl -L https://cdn.drmhse.com/servos/latest/servos-linux-x86_64 -o servos
chmod +x servos
sudo mv servos /usr/local/bin/

# 2. Create the configuration and data directories
sudo mkdir -p /etc/servos /var/lib/servos

# 3. Generate a Setup Token
# This token is required to create the first admin account via the dashboard.
openssl rand -hex 16 | sudo tee /var/lib/servos/setup_token
sudo chmod 600 /var/lib/servos/setup_token

# OR (Development Mode / Non-Root)
export SERVOS_DATA_DIR=$(pwd)/servos-data
mkdir -p $SERVOS_DATA_DIR
cargo run --bin servos-api -- reset-setup-token

3. Start the Server

If you used the automated installer:

sudo systemctl start servos

If you are running manually:

# Set required environment variables
export DATABASE_URL="sqlite:///var/lib/servos/servos.db"
export SERVOS_MASTER_KEY="your-32-byte-encryption-key"
export AUTHOS_URL="https://sso.example.com"
export AUTHOS_AUDIENCE="servos"

# Run the server
servos

4. Access the Dashboard

Open http://localhost:8080 (default port) in your browser to access the ServOS dashboard.

5. Initial Setup (First-to-Claim)

When you first access the dashboard, you will be prompted for a Setup Token. This is a security measure to ensure that only the person who installed ServOS can create the initial administrator account.

• Setup Token: Located at /var/lib/servos/setup_token on the server.
• Master Key: Located in /etc/servos/servos.env.

[!CAUTION] Save Your Master Key: The Master Key is used to encrypt all sensitive data (passwords, private keys) in the database. If you lose this key, you will lose access to all managed servers and services. Keep it in a secure password manager.

Add Your First Server

1. Navigate to Servers in the dashboard

2. Click Add Server

3. Enter your server details:

   • Name: A friendly name (e.g., “production-1”)
   • IP Address: Your server’s public IP
   • SSH User: Usually “root” or your admin user
   • SSH Private Key: Your private key for authentication

4. Click Commission to install Docker, Traefik, and the ServOS Agent (for networking & observability).

   [!IMPORTANT] Firewall Requirement: All servers in your cluster must allow inbound traffic on UDP port 51820 from each other’s public IPs. This is required for the WireGuard Mesh private network.

Deploy Your First Service

1. Navigate to Services in the dashboard
2. Click Create Service
3. Configure your service:
   • Name: Your application name
   • Repository URL: Git repository containing your Dockerfile
   • Branch: The branch to deploy (default: “main”)
   • Domain: Your application’s domain
4. Click Deploy

ServOS will:

• Clone your repository
• Auto-detect your project type or use your Dockerfile
• Build the Docker image
• Push to your configured registry
• Deploy with zero-downtime blue/green switching

[!TIP] No Dockerfile? ServOS uses Nixpacks to automatically generate optimized Dockerfiles for Node.js, Python, Go, and Rust projects.

Next Steps

• Understanding Deployments - Learn how blue/green deployments work
• CLI Reference - Manage ServOS from your terminal
• Environment Variables - Configure secrets and configuration
• Custom Domains - Set up SSL and routing