name: servel
description: Self-hosted deployment platform via Docker Swarm. Deploys applications, manages 45+ infrastructure types (databases, queues, caches, platforms), handles secrets, domains, backups, and server operations. Triggers on deploy, infrastructure, postgres, redis, supabase, backup, restore, logs, secrets, SSL, domains, dev mode, CI/CD, alerts, traefik, routing, or server management.

Servel

Deploy applications and infrastructure to Docker Swarm with Vercel-like simplicity. Auto-detects project type, provisions SSL, zero-downtime rolling updates.

Decision Tree

Task → What are you trying to do?
│
├─ Deploy app → servel deploy
│   ├─ Need database? → servel add postgres --name db && servel deploy --link-infra db
│   ├─ Preview/PR? → servel deploy --preview --ttl 24h
│   └─ Multi-env? → servel deploy --env production
│
├─ Add infrastructure → servel add <type> --name <name>
│   ├─ Bundle? → servel add redis,postgres --prefix app
│   ├─ High-availability? → servel add postgres --name db --ha
│   └─ Link to app? → servel link myapp --infra db
│
├─ Debug/inspect → servel logs <name> -f | servel exec <name> sh
│   └─ Infra? → Use @ prefix: servel logs @mydb -f | servel exec @mydb --service rails sh
│
├─ Dev mode → servel dev
│   └─ Team sync? → servel dev --team
│
├─ Manage server → servel server status | servel ssh <server>
│
├─ Routing issues → servel traefik status | servel verify dns <domain>
│
└─ Backup/restore → servel infra backup <name> | servel infra restore <name> <file>

Service Addressing (Symbol Prefixes)

Most commands that target a service (exec, logs, inspect, stats, restart, stop, start, scale, env, remove) support symbol prefixes:

For multi-service infrastructure (chatwoot, supabase, etc.), use --service:

servel exec @chatwoot --service rails sh
servel logs @supabase --service postgres -f
servel restart @chatwoot --service sidekiq

Quick Reference

Deploy

servel deploy                         # Auto-detect & deploy
servel deploy --preview --ttl 24h     # Preview with cleanup
servel deploy --link-infra db,redis   # Link infrastructure
servel deploy --dry-run               # Show plan only
servel deploy --no-registry           # Skip registry (single-node)
servel deploy --env staging           # Multi-environment
servel deploy --verbose               # Full build output
servel deploy --rebuild               # Force rebuild, skip cache
servel deploy --memory 1g --cpu 0.5   # Resource limits
servel ps                             # List deployments
servel ps --all-servers               # List across all servers
servel ps --tree                      # Tree view with dependencies
servel logs <name> -f                 # Follow logs
servel watch <name>                   # Watch deploy progress (TUI)
servel rm <name>                      # Remove
servel rollback <name>                # Rollback version
servel scale <name> 3                 # Scale replicas
servel restart <name>                 # Restart deployment
servel stop <name>                    # Stop deployment
servel start <name>                   # Start stopped deployment
servel rename <old> <new>             # Rename deployment
servel exec <name> sh                 # Shell into container
servel exec <name> -- cmd args        # Run command in container
servel inspect <name>                 # Detailed deployment info
servel history <name>                 # Deployment history
servel versions <name>                # Available versions

Detection priority: servel.yaml → docker-compose.yml → Dockerfile → preset → Nixpacks

Smart mode (default): Detects what changed → config-only (~8s), static-only (~10s), or full build.

Key flags:
- --name, -n — Deployment name
- --domain, -d — Domain for routing
- --preview — Preview environment
- --ttl — Preview lifetime (1h, 6h, 1d, 7d, 2w)
- --link-infra — Link infrastructure (comma-separated)
- --no-registry — Skip registry push
- --rebuild — Force rebuild
- --no-smart — Disable smart detection
- --verbose — Show full build output
- --env — Target environment
- --build-on <node> — Build on specific node
- --local-build — Build locally, push to registry

Deploy Aliases

Define deployment presets in servel.yaml:

deploy:
  aliases:
    preview:
      ttl: "0"
      domain: "{branch}.preview.myapp.com"
      no_index: true
    quick:
      fast: true
      local: true
    staging:
      env: staging
      domain: "staging.myapp.com"

Usage: servel deploy preview, servel deploy quick
- If a directory exists with that name → deploys directory
- Otherwise → applies alias settings

Infrastructure (45+ types)

servel add postgres --name db         # Create
servel add redis,postgres --prefix app # Bundle multiple
servel add postgres --name db --ha    # High-availability
servel add supabase --name supa       # Full platform stack
servel add chatwoot --var Domain=chat.example.com  # Auto-init on first deploy
servel infra status                   # Health check all
servel infra vars db                  # View env vars
servel logs @db -f                    # Follow infra logs (@ prefix)
servel logs @chatwoot --service rails -f  # Multi-service infra logs
servel infra backup db                # Backup
servel infra restore db backup.sql.gz # Restore
servel infra rotate db                # Rotate credentials
servel infra restart db --force       # Force restart
servel infra start db                 # Start
servel infra stop db                  # Stop
servel infra rename old new           # Rename
servel infra rm db                    # Remove
servel link myapp --infra db          # Link → injects DATABASE_URL
servel unlink myapp --infra db        # Unlink
servel deps myapp                     # Show dependencies
servel connect db                     # Quick connect to infra

Linking injects: DATABASE_URL, REDIS_URL, MONGODB_URI, etc. based on infrastructure type.

Lifecycle hooks: Some templates auto-run setup commands on first deploy (e.g., Chatwoot runs db:chatwoot_prepare).

Node pinning:
- --node hostname — By hostname
- --alias db-node — By alias
- --label storage=ssd — By node label

Server Management

servel ssh <server>                   # SSH into server
servel server status                  # Cluster health (CPU, memory, disk)
servel server add <name> user@host    # Add server
servel server list                    # List servers
servel server use <name>              # Switch default server
servel server remove <name>           # Remove server
servel server provision               # Automated setup
servel server domain set example.com  # Set primary domain
servel server keys add <name> --key-file pubkey.pub # Add deploy key
servel node ls                        # List swarm nodes
servel node add worker user@host      # Add node to cluster
servel node remove <name>             # Remove node
servel node promote <name>            # Promote to manager
servel node health <name>             # Check node health
servel node specs <name>              # Node specifications
servel df                             # Disk usage
servel df --volumes                   # Volume usage by category
servel df --nodes                     # Per-node usage
servel doctor                         # Diagnose issues
servel cleanup                        # Remove expired environments
servel cleanup --force                # No confirmation
servel prune                          # Remove dangling images/containers
servel prune --all                    # Remove unused images/networks/cache
servel prune --all --volumes          # ⚠️ DATA LOSS: removes unused volumes

Secrets

servel secrets set API_KEY            # Set (prompted input)
servel secrets set API_KEY "value"    # Set with value
servel secrets list                   # List keys
servel secrets get API_KEY            # Get value
servel secrets rm API_KEY             # Remove
servel secrets rotate API_KEY         # Rotate
servel secrets backup                 # Backup all secrets
servel secrets scan                   # Scan for exposed secrets
servel deploy --migrate-secrets       # Auto-detect *_KEY, *_SECRET, *_PASSWORD

Domains & Routing

servel domains add myapp app.com      # Add domain (auto-SSL)
servel domains ls                     # List all domains
servel domains rm myapp app.com       # Remove domain
servel domains redirect old.com new.com # Create redirect
servel domains remove-redirect old.com # Remove redirect
servel domains list-redirects         # List redirects
servel routes <name>                  # Show deployment routes

Traefik (Routing Layer)

servel traefik status                 # Router status
servel traefik logs                   # Traefik logs
servel traefik routes <name>          # Detailed route info
servel traefik certs                  # SSL certificate info
servel traefik test <domain>          # Test domain routing
servel traefik restart                # Restart Traefik

Verification

servel verify <name>                  # Full verification
servel verify config                  # Verify configuration
servel verify health <name>           # Check service health
servel verify ssl <domain>            # Check SSL certificates
servel verify dns <domain>            # Check DNS configuration
servel verify routing <name>          # Check Traefik routing
servel verify dependencies <name>     # Check dependencies
servel verify resources               # Check resource availability

Dev Mode

servel dev                            # Start dev session
servel dev --team                     # Bidirectional sync (collaboration)
servel dev --port 3001                # Custom port
servel dev --domain staging.app.com   # Custom domain
servel dev --no-sync                  # One-time upload only
servel dev --conflict-policy newer-wins # Sync conflict resolution
servel dev list                       # Active sessions
servel dev logs <id> -f               # Follow session logs
servel dev stop <id>                  # Stop session
servel tunnel                         # Expose localhost publicly
servel tunnel start <port>            # Start tunnel on port
servel tunnel list                    # List active tunnels
servel tunnel stop <id>               # Stop tunnel
servel port-forward db 5432           # Forward remote port locally

Conflict policies: remote-wins, local-wins, newer-wins, backup

Environment Variables

servel env set <name> KEY=VALUE       # Set env var
servel env vars <name>                # Show env vars
servel env list                       # List environments
servel config show <name>             # Show deployment config
servel config sync <name>             # Sync config to servel.yaml
servel config sync --dry-run          # Preview sync

Alerts

servel alerts setup                   # Interactive wizard
servel alerts add telegram            # Add Telegram channel
servel alerts add slack               # Add Slack channel
servel alerts add discord             # Add Discord channel
servel alerts add webhook             # Add webhook
servel alerts test                    # Test notifications
servel alerts status                  # Show alert status
servel alerts history                 # View alert history
servel alerts pause 2h                # Maintenance mode (pause alerts)

CI/CD

servel ci init github                 # Initialize GitHub Actions
servel ci init gitlab                 # Initialize GitLab CI
servel ci list                        # List pipelines
servel ci run <config>                # Run built-in CI
servel ci status <run-id>             # Check run status
servel ci logs <run-id>               # View CI logs
servel ci recent                      # Recent runs
servel ci cancel <run-id>             # Cancel run
servel ci retry <run-id>              # Retry run

Access Control

servel auth login                     # User authentication
servel auth logout                    # Logout
servel auth whoami                    # Current user info
servel auth enable <name>             # Enable basic auth
servel auth disable <name>            # Disable basic auth
servel access user                    # User management
servel access role                    # Role management

Advanced

servel detect                         # Detect project build type
servel detect --verbose               # Detailed detection info
servel init                           # Initialize servel.yaml
servel validate                       # Validate servel.yaml
servel upgrade                        # Self-upgrade CLI
servel upgrade-servers                # Upgrade server binaries
servel audit list                     # View audit logs
servel audit stats                    # Audit statistics
servel tag <name> <tag>               # Add tags to deployment
servel untag <name> <tag>             # Remove tags

Common Workflows

Deploy with Database

servel add postgres --name mydb
servel deploy --link-infra mydb
# App receives DATABASE_URL, DB_HOST, DB_PORT, DB_PASSWORD

Preview Deployments

servel deploy --preview --ttl 24h
# Returns: https://myapp-pr42.example.com

Multi-Environment

servel deploy --env production
servel deploy --env staging
servel deploy --preview

Debug Container

servel logs myapp -f                  # View logs
servel exec myapp sh                  # Shell into container
servel exec myapp -- cat /app/.env    # Run command
servel logs @mydb -f                  # View infra logs (@ prefix)
servel exec @chatwoot --service rails sh  # Multi-service infra

Backup & Restore

servel infra backup mydb
servel infra restore mydb backup-2024-01-15.sql.gz

CI/CD Deploy Keys

servel server keys add prod --name github-actions --key-file pubkey.pub

Troubleshoot Routing

servel verify dns app.example.com     # Check DNS
servel verify ssl app.example.com     # Check SSL
servel traefik test app.example.com   # Test routing
servel traefik logs                   # View Traefik logs

Configuration (servel.yaml)

name: myapp
domain: app.example.com

build:
  preset: bun                         # bun, node, python, go
  dockerfile: Dockerfile
  buildCommand: bun run build
  startCommand: bun run start

env:
  NODE_ENV: production

secrets:
  - API_KEY
  - DB_PASSWORD

resources:
  memory: 512M
  cpus: 0.5

replicas: 2

healthcheck:
  type: http                          # http, tcp, cmd, none
  path: /health
  interval: 30s
  timeout: 10s
  retries: 3

update:
  order: start-first                  # start-first, stop-first
  failure_action: rollback            # rollback, pause, continue

infra:
  - name: mydb
    prefix: DB                        # → DB_HOST, DB_PORT, DB_PASSWORD

routes:
  - type: http
    domain: app.example.com
    port: 3000
  - type: http
    domain: api.example.com
    path: /v1/*
    port: 3001

persist:
  - /app/data
  - /app/uploads

dev:
  command: bun run dev
  port: 3000
  sync:
    ignore:
      - "*.log"
      - ".cache"

environments:
  production:
    domain: myapp.com
    replicas: 5
  staging:
    domain: staging.myapp.com
  preview:
    ttl: 7d

Aliases

Troubleshooting

Diagnostic commands:

servel doctor                         # System check
servel verify health <name>           # Health check
servel verify dns <domain>            # DNS check
servel verify ssl <domain>            # SSL check
servel traefik status                 # Routing status
servel logs <name>                    # View logs
servel inspect <name>                 # Deployment details

Reference Files

• Template Building Guide - Create custom infrastructure types
• Full docs: https://servel.dev/docs
• Infrastructure Hub: https://hub.servel.dev