Core Concepts

Understanding these core concepts will help you get the most out of ServOS.

Architecture Overview

ServOS is built around a simple but powerful architecture:

┌─────────────────────────────────────────────────────────┐
│                      ServOS Dashboard                       │
│                      (servos-app)                          │
└─────────────────────┬───────────────────────────────────┘
                      │ REST API
┌─────────────────────▼───────────────────────────────────┐
│                      ServOS API                            │
│                     (servos-api)                           │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │ Servers │  │Services │  │ Deploy  │  │ Backups │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
└─────────────────────┬───────────────────────────────────┘
                      │ SSH
┌─────────────────────▼───────────────────────────────────┐
│                   Your Servers                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Traefik   │  │  Your App   │  │  servos-agent  │    │
│  │   (Proxy)   │  │(Any Runtime)│  │  (Daemon)   │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────────────────────────────────────────┘

Servers

A Server is a Linux host that ServOS manages. When you commission a server, ServOS:

• Installs Docker
• Installs servos-agent (for observability & mesh networking)
• Configures log rotation
• Sets up the servos-network Docker network
• Deploys Traefik as the ingress proxy
• Configures firewall rules (UFW)

Services

A Service is an application you want to deploy. Each service has:

• Name: Unique identifier
• Repository: Git URL for your source code
• Dockerfile: Path to your Dockerfile (default: Dockerfile)
• Domain: The public domain for your service
• Environment Variables: Configuration and secrets

Blue/Green Deployments

ServOS uses blue/green deployments for zero-downtime updates:

1. Build: ServOS builds a new container image
2. Deploy Blue: The new version starts as the “blue” container
3. Health Check: ServOS verifies the new container is healthy
4. Switch Traffic: Traefik routes traffic to the new container
5. Cleanup: The old “green” container is removed

If anything fails, traffic stays on the old container.

Traefik Integration

ServOS uses Traefik as the reverse proxy:

• Automatic HTTPS: Let’s Encrypt certificates
• Docker Integration: Auto-discovers containers via labels
• Load Balancing: Routes traffic to healthy containers
• Middleware: Redirects, headers, rate limiting

Next Steps

• Deployments - Deep dive into the deployment process
• Networking - How services communicate
• Observability - Host, container, mesh, and agent health metrics
• Storage - Volumes and persistent data