Zero-downtime Docker deployments.

Deploy containers to production with automatic SSL, rolling updates, and simple YAML config. No Kubernetes required.

Get startedView on GitHub
deploy.yml
secrets.yml.enc
service: myapp
image: registry.example.com/myapp


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


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

Introduction

Getting started

Deploy Docker containers to production with zero-downtime, automatic SSL, and encrypted secrets. No Kubernetes required.

Installation

Install the Odysseus gems and set up your first deployment configuration.

Configuration

Learn how to configure services, servers, proxy settings, and more.

Deployment

Deploy your applications with rolling updates and health checks.

CLI Reference

Complete reference for all Odysseus commands and options.

Odysseus is a production-grade deployment tool that makes it simple to deploy Docker containers to any server with SSH access. It handles the complexity of zero-downtime deployments, SSL certificates, and service orchestration so you can focus on building your application.

Quick start

Get your first deployment running in minutes. Odysseus uses a single deploy.yml file to define your entire deployment configuration.

Install Odysseus

Odysseus is distributed as Ruby gems. Install the CLI tool to get started:

gem install odysseus-cli

Or add it to your Gemfile for project-specific installations:

gem 'odysseus-cli'

Create your configuration

Create a deploy.yml file in your project root:

service: myapp
image: myregistry/myapp

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

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

env:
  clear:
    RAILS_ENV: production
  secret:
    - DATABASE_URL
    - RAILS_MASTER_KEY

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

Prerequisites

Your target server needs Docker and Caddy installed. Odysseus manages Docker containers and configures Caddy as a reverse proxy for automatic HTTPS.

Deploy your application

Build your Docker image and deploy:

odysseus deploy --build --image latest

Odysseus will:

  1. Build your Docker image locally
  2. Transfer it to your server (or push to a registry)
  3. Start the new container
  4. Wait for health checks to pass
  5. Update Caddy to route traffic to the new container
  6. Gracefully drain the old container
  7. Clean up old containers

First deployment

On first deployment, Odysseus will set up Caddy routes and obtain SSL certificates. Make sure your DNS is configured to point to your server.

Core concepts

Understanding these concepts will help you get the most out of Odysseus.

Services and roles

A service is your application. Each service can have multiple roles:

  • web: HTTP services that receive traffic through Caddy
  • jobs: Background workers (like Sidekiq or GoodJob)
  • Custom roles with specific commands

Zero-downtime deployments

Odysseus achieves zero-downtime through a rolling deployment strategy:

  1. New container starts alongside the old one
  2. Health checks verify the new container is ready
  3. Caddy adds the new container to its upstream pool
  4. Old container is gracefully drained
  5. Old container is stopped after connections close

Secrets management

Sensitive values are stored in an encrypted file using AES-256-GCM encryption. Generate a master key and encrypt your secrets:

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

What's next?

Now that you understand the basics, dive deeper into specific topics:

Getting help

Odysseus is actively developed and we're here to help.

Report an issue

Found a bug or have a feature request? Open an issue on GitHub:

Contributing

Odysseus is open source and contributions are welcome. See the contributing guide to get started.

Next
Installation