Configuration reference

Complete reference for Odysseus configuration options in deploy.yml.

Configuration file

Odysseus uses a YAML configuration file, typically named deploy.yml, to define your deployment. This file describes your service, servers, proxy settings, environment variables, and more.

service: myapp
image: registry.example.com/myapp

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

proxy:
  hosts:
    - myapp.example.com
  app_port: 3000
  ssl: true

env:
  clear:
    RAILS_ENV: production
  secret:
    - DATABASE_URL

ssh:
  user: root
  keys:
    - ~/.ssh/id_ed25519

Service configuration

service

Required. The name of your service. Used for container naming and identification.

service: myapp

image

Required. The Docker image name (without tag). Tags are specified at deploy time.

image: registry.example.com/myapp

When using a registry:

image: ghcr.io/myorg/myapp

Server configuration

The servers section defines where your application runs and what roles each server has.

Basic structure

servers:
  web:
    hosts:
      - app1.example.com
      - app2.example.com
    options:
      memory: 4g
      cpus: 2
  jobs:
    hosts:
      - worker.example.com
    cmd: bundle exec good_job

Roles

Each key under servers is a role:

• web: HTTP services that receive traffic through Caddy
• jobs: Background workers without HTTP access
• Custom roles with specific commands

hosts

List of hostnames or IP addresses for this role.

servers:
  web:
    hosts:
      - 10.0.1.10
      - 10.0.1.11

cmd

Override the container's default command.

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

options

Docker run options for containers in this role.

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

Available options:

• memory: Memory limit (e.g., 4g, 512m)
• memory_reservation: Soft memory limit
• cpus: CPU limit (e.g., 2, 0.5)

Proxy configuration

The proxy section configures Caddy reverse proxy settings for web roles.

proxy:
  hosts:
    - myapp.example.com
    - www.myapp.example.com
  app_port: 3000
  ssl: true
  ssl_email: admin@example.com
  healthcheck:
    path: /health
    interval: 10
    timeout: 5

hosts

Domain names that Caddy will route to your application.

app_port

The port your application listens on inside the container.

ssl

Enable automatic HTTPS with Let's Encrypt.

ssl_email

Email address for Let's Encrypt certificate notifications.

healthcheck

HTTP health check configuration:

• path: Health check endpoint (default: /)
• interval: Seconds between checks (default: 10)
• timeout: Seconds to wait for response (default: 5)

Environment variables

The env section defines environment variables for your containers.

env:
  clear:
    RAILS_ENV: production
    RAILS_LOG_TO_STDOUT: "true"
  secret:
    - DATABASE_URL
    - RAILS_MASTER_KEY
    - REDIS_URL

clear

Plaintext environment variables stored directly in deploy.yml.

secret

List of environment variable names loaded from the encrypted secrets file.

secrets_file

Path to the encrypted secrets file.

secrets_file: secrets.yml.enc

See Secrets management for details.

Builder configuration

The builder section configures how Docker images are built.

builder:
  strategy: local
  arch: amd64
  dockerfile: Dockerfile
  context: .
  build_args:
    RUBY_VERSION: "3.2"
  cache: true
  push: false

strategy

Build strategy:

• local: Build on the machine running Odysseus
• remote: Build on a remote host via SSH

arch

Target architecture: amd64 or arm64.

dockerfile

Path to the Dockerfile (default: Dockerfile).

context

Build context path (default: .).

build_args

Build-time arguments passed to Docker.

cache

Enable Docker build cache (default: true).

push

Push to registry after build (default: false).

Remote builds

For remote builds:

builder:
  strategy: remote
  host: build-server.example.com
  arch: amd64

Registry configuration

Configure Docker registry authentication.

registry:
  server: ghcr.io
  username: myuser
  password: ${GITHUB_TOKEN}

When registry.server is present, Odysseus uses registry mode: images are pushed to the registry and pulled by hosts.

SSH configuration

Configure SSH connections to servers.

ssh:
  user: root
  keys:
    - ~/.ssh/id_ed25519
    - ~/.ssh/id_rsa

user

SSH username for connecting to servers.

keys

List of SSH private key paths.

Accessories

Define auxiliary services like databases. See Accessories for details.

accessories:
  db:
    image: postgres:16
    volumes:
      - /var/lib/odysseus/myapp/postgres:/var/lib/postgresql/data
    env:
      clear:
        POSTGRES_USER: myapp
        POSTGRES_DB: myapp_production

Complete example

service: myapp
image: ghcr.io/myorg/myapp

builder:
  strategy: local
  arch: amd64
  cache: true

registry:
  server: ghcr.io
  username: myuser
  password: ${GITHUB_TOKEN}

servers:
  web:
    hosts:
      - app1.example.com
      - app2.example.com
    options:
      memory: 4g
      cpus: 2
  jobs:
    hosts:
      - worker.example.com
    cmd: bundle exec good_job
    options:
      memory: 2g

proxy:
  hosts:
    - myapp.example.com
  app_port: 3000
  ssl: true
  ssl_email: admin@example.com
  healthcheck:
    path: /health
    interval: 10

env:
  clear:
    RAILS_ENV: production
    RAILS_LOG_TO_STDOUT: "true"
  secret:
    - DATABASE_URL
    - RAILS_MASTER_KEY
    - REDIS_URL

secrets_file: secrets.yml.enc

accessories:
  db:
    image: postgres:16
    volumes:
      - /var/lib/odysseus/myapp/postgres:/var/lib/postgresql/data
    env:
      clear:
        POSTGRES_USER: myapp
        POSTGRES_DB: myapp_production
    healthcheck:
      cmd: pg_isready -U myapp

ssh:
  user: root
  keys:
    - ~/.ssh/id_ed25519