Deployment Guide

Production checklist

Before going to production:

• Set COSMICTRON_PERFORMANCE_PROFILE=production
• Mount a persistent volume for COSMICTRON_DATA_DIR
• Set COSMICTRON_JWT_SECRET to a random 256-bit secret
• Configure TLS (reverse proxy or built-in)
• Enable health check endpoints (/v1/health, /v1/health/ready)
• Set up log aggregation
• Configure Prometheus scraping at /metrics

Bare metal / VM

# 1. Copy binary
scp target/release/cosmictron-server user@prod-host:/usr/local/bin/

# 2. Create systemd unit
cat > /etc/systemd/system/cosmictron.service << EOF
[Unit]
Description=Cosmictron server
After=network.target

[Service]
Type=simple
User=cosmictron
ExecStart=/usr/local/bin/cosmictron-server
Environment=COSMICTRON_DATA_DIR=/var/lib/cosmictron
Environment=COSMICTRON_PERFORMANCE_PROFILE=production
Environment=COSMICTRON_JWT_SECRET=<your-secret>
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF

systemctl enable cosmictron
systemctl start cosmictron

Docker Compose

version: '3.8'
services:
  cosmictron:
    image: ghcr.io/cosmictron/cosmictron:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
      - "5432:5432"
    environment:
      COSMICTRON_DATA_DIR: /data
      COSMICTRON_PERFORMANCE_PROFILE: production
      COSMICTRON_JWT_SECRET: "${JWT_SECRET}"
      COSMICTRON_LOG: info
    volumes:
      - cosmictron-data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/v1/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  cosmictron-data:

Kubernetes

See the Installation page for the full Deployment manifest.

Additional resources for production:

# HorizontalPodAutoscaler — scale on CPU (note: single-node, so only scale stateless replicas of the frontend)
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: cosmictron
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: cosmictron
  minReplicas: 1
  maxReplicas: 1   # Keep at 1 until multi-region ships
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

Caution

Cosmictron is single-node. Do not run multiple replicas sharing the same COSMICTRON_DATA_DIR — this will corrupt the WAL. One replica per storage volume.

Fly.io

fly.toml

app = "my-cosmictron"
primary_region = "sin"

[build]
  image = "ghcr.io/cosmictron/cosmictron:latest"

[env]
  COSMICTRON_DATA_DIR = "/data"
  COSMICTRON_PERFORMANCE_PROFILE = "production"

[mounts]
  source = "cosmictron_data"
  destination = "/data"

[[services]]
  internal_port = 3000
  protocol = "tcp"
  [[services.ports]]
    port = 443
    handlers = ["tls", "http"]
  [[services.ports]]
    port = 80
    handlers = ["http"]
  [[services.http_checks]]
    path = "/v1/health"
    interval = "15s"
    timeout = "5s"

fly volumes create cosmictron_data --size 50
fly secrets set JWT_SECRET=$(openssl rand -hex 32)
fly deploy

TLS / Reverse proxy

Cosmictron does not terminate TLS natively. Use nginx or Caddy as a reverse proxy:

# nginx config
server {
    listen 443 ssl;
    server_name cosmictron.yourorg.com;

    ssl_certificate     /etc/ssl/certs/cosmictron.crt;
    ssl_certificate_key /etc/ssl/private/cosmictron.key;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";  # Required for WebSocket
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}