Skip to Content

Self-Hosted Deployment

TL;DR

Self-host CMDOP Control Plane on your own Linux server with PostgreSQL 14+ and Redis 6+. Download the binary, configure via config.yaml, set up TLS (Let’s Encrypt or manual), and run as a systemd service. Agents and SDKs connect to your server over gRPC with TLS.

Run CMDOP Control Plane on your own infrastructure.

What are the prerequisites?

  • Linux server (Ubuntu 22.04+ recommended)
  • PostgreSQL 14+
  • Redis 6+
  • TLS certificate
  • Domain name

How do I get started quickly?

# Download
curl -LO https://github.com/cmdop/cmdop/releases/latest/download/cmdop-server
 
# Make executable
chmod +x cmdop-server
 
# Configure
cp config.example.yaml config.yaml
# Edit config.yaml with your settings
 
# Run
./cmdop-server serve

How do I configure the server?

What goes in config.yaml?

# Server settings
server:
  http_port: 443
  grpc_port: 50051
  domain: cmdop.yourcompany.com
 
# TLS
tls:
  enabled: true
  cert_file: /etc/cmdop/cert.pem
  key_file: /etc/cmdop/key.pem
  # Or use Let's Encrypt
  auto_cert: true
  email: [email protected]
 
# Database
database:
  host: localhost
  port: 5432
  name: cmdop
  user: cmdop
  password: ${DB_PASSWORD}
 
# Redis
redis:
  host: localhost
  port: 6379
  password: ${REDIS_PASSWORD}
 
# Authentication
auth:
  # OAuth providers
  oauth:
    google:
      client_id: ${GOOGLE_CLIENT_ID}
      client_secret: ${GOOGLE_CLIENT_SECRET}
    github:
      client_id: ${GITHUB_CLIENT_ID}
      client_secret: ${GITHUB_CLIENT_SECRET}
 
  # JWT signing key
  jwt_secret: ${JWT_SECRET}
 
# Logging
logging:
  level: info
  format: json

How do I set up the database?

-- Create database and user
CREATE DATABASE cmdop;
CREATE USER cmdop WITH ENCRYPTED PASSWORD 'your-password';
GRANT ALL PRIVILEGES ON DATABASE cmdop TO cmdop;

Run migrations:

./cmdop-server migrate

How do I run CMDOP as a systemd service?

# /etc/systemd/system/cmdop.service
[Unit]
Description=CMDOP Control Plane
After=network.target postgresql.service redis.service
 
[Service]
Type=simple
User=cmdop
WorkingDirectory=/opt/cmdop
ExecStart=/opt/cmdop/cmdop-server serve
Restart=always
RestartSec=10
Environment=DB_PASSWORD=xxx
Environment=REDIS_PASSWORD=xxx
Environment=JWT_SECRET=xxx
 
[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable cmdop
sudo systemctl start cmdop

How do I set up TLS?

How do I use Let’s Encrypt?

tls:
  auto_cert: true
  email: [email protected]

How do I use a manual certificate?

tls:
  enabled: true
  cert_file: /etc/cmdop/fullchain.pem
  key_file: /etc/cmdop/privkey.pem

How do I configure agents to connect?

Configure agents to connect to your server:

# ~/.cmdop/config.yaml on agent machines
server:
  address: cmdop.yourcompany.com:50051
  tls: true

Or via environment:

export CMDOP_SERVER_ADDRESS=cmdop.yourcompany.com:50051

How do I configure the SDK to use my server?

# Point the SDK to your self-hosted server instead of the cloud endpoint
client = AsyncCMDOPClient.remote(
    api_key="cmd_xxx",
    server="cmdop.yourcompany.com:50052"  # Your self-hosted gRPC endpoint
)

How do I check server health?

# Check HTTP health endpoint returns 200 OK
curl https://cmdop.yourcompany.com/health
 
# Verify gRPC endpoint is responding using grpcurl
grpcurl cmdop.yourcompany.com:50051 grpc.health.v1.Health/Check

How do I back up CMDOP?

How do I back up the database?

pg_dump -h localhost -U cmdop cmdop > backup.sql

How do I back up the configuration?

# Archive config files and TLS certs into a compressed tarball
tar -czf cmdop-config.tar.gz /opt/cmdop/config.yaml /etc/cmdop/

How do I upgrade to a new version?

# Stop service
sudo systemctl stop cmdop
 
# Backup
cp cmdop-server cmdop-server.backup
 
# Download new version
curl -LO https://github.com/cmdop/cmdop/releases/latest/download/cmdop-server
chmod +x cmdop-server
 
# Run migrations
./cmdop-server migrate
 
# Start service
sudo systemctl start cmdop

How do I troubleshoot common issues?

What if the connection is refused?

# Check service is running
sudo systemctl status cmdop
 
# Check ports
ss -tlnp | grep -E '443|50051'
 
# Check firewall
sudo ufw status

How do I debug database connection problems?

# Test connection
psql -h localhost -U cmdop cmdop
 
# Check logs
journalctl -u cmdop -f

How do I fix TLS issues?

# Test TLS handshake and view certificate chain
openssl s_client -connect cmdop.yourcompany.com:443
 
# Check certificate expiry dates to avoid unexpected downtime
openssl x509 -in /etc/cmdop/cert.pem -noout -dates
Last updated on
Overview