Odysseus

Zero-downtime Docker deployments over SSH with automatic HTTPS.

Beta: Odysseus is under active development. APIs and configuration may change. Feedback and contributions welcome!

Odysseus deploys containerized applications to your own servers using SSH, Docker, and Caddy. No Kubernetes. No container orchestration platform. Just simple, reliable deployments.

• Zero-downtime deployments - New containers start before old ones stop
• Automatic HTTPS - Caddy handles SSL certificates via Let's Encrypt
• No registry required - Push images directly to servers via SSH with pussh
• Minimal server requirements - Just Docker and SSH access
• Familiar configuration - YAML config inspired by Kamal

┌─────────────┐     SSH      ┌─────────────────────────────────────┐
│   odysseus  │─────────────▶│            Your Server              │
│     CLI     │              │  ┌───────────┐    ┌──────────────┐  │
└─────────────┘              │  │   Caddy   │───▶│  App (new)   │  │
                             │  │  (proxy)  │    └──────────────┘  │
                             │  └───────────┘    ┌──────────────┐  │
                             │        │         │  App (old)   │  │
                             │        └────────▶│  (draining)  │  │
                             │                  └──────────────┘  │
                             └─────────────────────────────────────┘

1. Build your Docker image locally
2. Push it to servers via SSH (or registry)
3. Start new container, wait for health check
4. Update Caddy routing to new container
5. Drain connections from old container
6. Stop and clean up old containers

Install the CLI:

gem install odysseus-cli

Create deploy.yml:

service: myapp
image: myapp

servers:
  web:
    hosts:
      - app.example.com

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

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

Deploy:

odysseus deploy --build --image v1.0.0

Deploy different container configurations to different servers:

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

Manage databases, Redis, and other services:

accessories:
  db:
    image: postgres:16
    hosts:
      - db.example.com
    volumes:
      - /var/lib/odysseus/myapp/postgres:/var/lib/postgresql/data

Store sensitive environment variables securely:

odysseus secrets generate-key
odysseus secrets encrypt --input secrets.yml --file secrets.yml.enc

Configurable health checks ensure containers are ready before receiving traffic:

proxy:
  healthcheck:
    path: /health
    interval: 10
    timeout: 5
    expect_status: 200

Dynamically resolve hosts from AWS ASGs:

servers:
  web:
    aws:
      asg: my-web-asg
      region: us-east-1

See odysseus-cli/README.md for complete CLI documentation and configuration reference.

odysseus/
├── odysseus-core/    # Core library (config parsing, deployers, orchestrators)
└── odysseus-cli/     # Command-line interface

cd odysseus-core
bundle install
bundle exec rspec

Local machine:

• Ruby 3.2+
• Docker (for building images)

Target servers:

• Docker
• SSH access

Caddy is automatically deployed as a container - no manual installation needed.

• Odysseus Pro (coming soon) - Web dashboard, team management, deployment history, and more

MIT

OpenSource is great. You can get inspiration from projects, do something different that fits your needs, and turn a page at the same time. — T.R^3