Servers and roles

Configure deployment targets and define application roles.

Understanding roles

Odysseus uses roles to organize how your application runs across servers. Each role represents a different type of workload.

Built-in roles

• web: HTTP services that receive traffic through Caddy's reverse proxy
• jobs: Background workers that process queues (Sidekiq, GoodJob, etc.)

Custom roles

You can define any role name for custom workloads:

servers:
  web:
    hosts:
      - web1.example.com
  jobs:
    hosts:
      - worker1.example.com
    cmd: bundle exec sidekiq
  scheduler:
    hosts:
      - worker1.example.com
    cmd: bundle exec clockwork clock.rb

Server configuration

Static hosts

The simplest configuration lists hosts directly:

servers:
  web:
    hosts:
      - app1.example.com
      - app2.example.com
      - app3.example.com

Hosts can be hostnames or IP addresses:

servers:
  web:
    hosts:
      - 10.0.1.10
      - 10.0.1.11

AWS Auto Scaling Groups

For dynamic infrastructure, Odysseus can discover hosts from AWS Auto Scaling Groups:

servers:
  web:
    aws:
      asg: production-asg
      region: us-east-1
      use_private_ip: true
      state: InService

See Host providers for details.

Container options

Configure Docker container settings per role.

Memory limits

servers:
  web:
    hosts:
      - app.example.com
    options:
      memory: 4g
      memory_reservation: 2g

• memory: Hard memory limit
• memory_reservation: Soft limit (guaranteed minimum)

CPU limits

servers:
  web:
    hosts:
      - app.example.com
    options:
      cpus: 2

Combined example

servers:
  web:
    hosts:
      - app.example.com
    options:
      memory: 4g
      memory_reservation: 2g
      cpus: 2
  jobs:
    hosts:
      - worker.example.com
    cmd: bundle exec sidekiq
    options:
      memory: 8g
      cpus: 4

Custom commands

Override the container's default command for specific roles.

Background workers

servers:
  jobs:
    hosts:
      - worker.example.com
    cmd: bundle exec sidekiq -c 10

Multiple worker types

servers:
  sidekiq:
    hosts:
      - worker1.example.com
    cmd: bundle exec sidekiq -q default -q mailers
  good_job:
    hosts:
      - worker2.example.com
    cmd: bundle exec good_job
  scheduler:
    hosts:
      - worker1.example.com
    cmd: bundle exec clockwork clock.rb

Multi-server deployments

Load balancing

Deploy web role to multiple servers for high availability:

servers:
  web:
    hosts:
      - app1.example.com
      - app2.example.com
      - app3.example.com

Odysseus deploys to each server sequentially, ensuring zero-downtime.

Separating workloads

Run different roles on dedicated servers:

servers:
  web:
    hosts:
      - web1.example.com
      - web2.example.com
    options:
      memory: 4g
  jobs:
    hosts:
      - worker1.example.com
      - worker2.example.com
    cmd: bundle exec sidekiq
    options:
      memory: 8g

Colocated services

Run multiple roles on the same server:

servers:
  web:
    hosts:
      - app.example.com
  jobs:
    hosts:
      - app.example.com
    cmd: bundle exec sidekiq

Both roles deploy to the same host but run as separate containers.

Deployment order

Odysseus deploys roles in the order they appear in the configuration:

1. First role deploys to all its hosts
2. Second role deploys to all its hosts
3. And so on...

For each host, Odysseus:

1. Starts new container
2. Waits for health checks
3. Updates routing (web only)
4. Drains old container
5. Cleans up

This ensures zero-downtime even during multi-server deployments.