Installation

Install Odysseus and set up your development environment.

Requirements

Before installing Odysseus, ensure you have the following:

Local machine

• Ruby 3.2+ - Odysseus is built with Ruby
• Docker - Required for building images locally
• docker-pussh - The Docker CLI plugin that carries images to your servers. Not bundled with Docker; see The docker-pussh plugin below
• SSH access - To your target servers

Target servers

Your deployment servers need:

• SSH access - Odysseus connects via SSH to manage deployments
• Docker - either already running, or a supported Ubuntu release (24.04 or 26.04) plus odysseus setup, which installs it for you

Deploys themselves never check the distro - any host with a working Docker daemon and SSH access will do. Only setup requires Ubuntu, because installing packages means knowing the package manager.

Installing Odysseus

Via RubyGems (recommended)

Install the CLI globally:

gem install odysseus-cli

Verify the installation:

odysseus --version

Via Bundler

Add to your project's Gemfile:

gem 'odysseus-cli'

Then install:

bundle install

Run commands with bundler:

bundle exec odysseus deploy

From source

Clone the repository and install locally:

git clone https://github.com/WA-Systems-EU/odysseus.git
cd odysseus
gem build odysseus-cli.gemspec
gem install odysseus-cli-*.gem

The docker-pussh plugin

The CLI on its own cannot move an image to a server. odysseus deploy --build shells out to docker pussh, a Docker CLI plugin from unregistry that Docker does not ship with. Without it, a deploy builds your image and then fails at distribution.

Install it on the machine you deploy from - not on your servers:

# macOS/Linux
mkdir -p ~/.docker/cli-plugins
curl -fsSL https://github.com/psviderski/unregistry/releases/latest/download/docker-pussh-$(uname -s)-$(uname -m) \
  -o ~/.docker/cli-plugins/docker-pussh && chmod +x ~/.docker/cli-plugins/docker-pussh

See build & pussh for what the plugin does during a deploy.

Server setup

Your target servers need Docker and SSH access. Odysseus handles everything else.

Prepare a host with odysseus setup

For a fresh Ubuntu 24.04 or 26.04 host, odysseus setup does the work for you: it creates a non-root deploy user, adds it to the docker group, installs your public key, and installs Docker itself if the host doesn't have it.

odysseus setup

Then verify the host with odysseus doctor:

odysseus doctor

setup is for getting a single host going, not for provisioning a fleet - preparing servers at scale belongs to OpenTofu, Terraform or an equivalent tool. Whichever way a host was prepared, run doctor afterwards to confirm it is actually usable.

Prepare a host manually

For a host that isn't Ubuntu, or one you provision yourself - by hand, or with a tool like OpenTofu - install Docker and configure access manually. It is also the right answer for a tofu-built host: the provisioning tool does this work, and doctor verifies the result.

On Ubuntu/Debian:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

On other distributions, follow the official Docker installation guide.

Caddy (automatic)

Odysseus automatically deploys and manages Caddy as a Docker container. On your first deploy, Odysseus will:

1. Create the odysseus Docker network
2. Start the odysseus-caddy container
3. Configure SSL certificates via Let's Encrypt
4. Set up routing to your application

No manual Caddy installation is required.

Configure SSH access

Odysseus connects to servers via SSH as the user ssh.user names. If you ran setup, it installed your key for that user already and proved the login works, so there is nothing to do here. For a host you prepared yourself, authorize the key by hand — substituting the deploy user for deploy below, or root if that is what your config names:

ssh-copy-id deploy@your-server.example.com

Test the connection as that same user, since that is the login deploys use:

ssh deploy@your-server.example.com "docker --version"

Project setup

Once Odysseus is installed, create a configuration file in your project.

Initialize 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

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

Validate configuration

Check your configuration for errors:

odysseus validate

First deployment

Deploy your application:

odysseus deploy --build --image v1.0.0

Next steps

• Configuration reference - Learn all configuration options
• Deployment - Understand the deployment process
• Secrets management - Set up encrypted secrets