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
• SSH access - To your target servers

Target servers

Your deployment servers need:

• Docker - For running containers
• SSH access - Odysseus connects via SSH to manage deployments

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/odysseus.git
cd odysseus
gem build odysseus-cli.gemspec
gem install odysseus-cli-*.gem

Server setup

Your target servers only need Docker installed. Odysseus handles everything else.

Install Docker

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. Ensure your SSH key is authorized on the target server:

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

Test the connection:

ssh root@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