Odysseus - Zero-downtime Docker deployments

Help improve Odysseus by contributing code, documentation, or bug reports.

Getting started

Prerequisites

Ruby 3.2+
Docker
Git

Clone the repository

git clone https://github.com/wa-systems/odysseus.git
cd odysseus

Install dependencies

bundle install

Run tests

bundle exec rspec

Project structure

Odysseus is organized as a monorepo with two gems:

odysseus/
├── odysseus-core/          # Core library
│   ├── lib/
│   ├── spec/
│   └── odysseus-core.gemspec
├── odysseus-cli/           # Command-line interface
│   ├── lib/
│   ├── exe/
│   ├── spec/
│   └── odysseus-cli.gemspec
├── doc-site/               # Documentation (this site)
└── test-deploy/            # Test configurations

Development workflow

Create a branch

git checkout -b feature/your-feature-name

Make changes

Write your code
Add tests
Update documentation if needed

Run tests

# Run all tests
bundle exec rspec

# Run specific tests
bundle exec rspec spec/deployer_spec.rb

# Run with coverage
COVERAGE=true bundle exec rspec

Lint code

bundle exec rubocop

Test locally

Create a test configuration:

# test-deploy/deploy.yml
service: test-app
image: nginx:alpine
servers:
  web:
    hosts:
      - localhost

Test commands:

cd odysseus-cli
bundle exec exe/odysseus validate --config ../test-deploy/deploy.yml

Code style

Ruby style

We use RuboCop for code style. Configuration is in .rubocop.yml.

Key guidelines:

2-space indentation
80-character line limit (soft)
Use snake_case for methods and variables
Use CamelCase for classes and modules

Commit messages

Use conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation
refactor: Code refactoring
test: Adding tests
chore: Maintenance

Examples:

feat(deploy): add support for AWS ASG host provider

fix(secrets): handle missing master key gracefully

docs(readme): update installation instructions

Pull requests

Before submitting

Tests pass: bundle exec rspec
No lint errors: bundle exec rubocop
Documentation updated if needed
Commit messages follow conventions

PR description

Include:

What the PR does
Why it's needed
How to test it
Any breaking changes

Review process

Submit PR against main branch
Automated tests run
Maintainer reviews
Address feedback
Merge when approved

Reporting bugs

Before reporting

Search existing issues
Try latest version
Check documentation

Bug report template

Include the following information:

Description: A clear description of the bug.

Steps to reproduce:

Run odysseus deploy ...
See error

Expected behavior: What should happen.

Actual behavior: What actually happens.

Environment:

Odysseus version
Ruby version
OS
Docker version

Configuration: Relevant parts of deploy.yml

Error output: Full error message

Feature requests

Submitting ideas

Open an issue with:

Clear description of the feature
Use case / why it's needed
Proposed implementation (optional)
Alternatives considered

Discussion

We'll discuss:

Whether it fits the project scope
Implementation approach
Timeline and priority

Documentation

Running docs locally

cd doc-site
npm install
npm run dev

Visit http://localhost:3000

Editing documentation

Documentation is in doc-site/src/app/docs/:

docs/
├── installation/page.md
├── configuration/page.md
├── deployment/page.md
└── ...

Use Markdown with Markdoc tags. Each page starts with YAML frontmatter containing the title, followed by content using standard Markdown plus special Markdoc tags like {% callout %} for notes and warnings.

Release process

Releases are managed by maintainers:

Update version in gemspecs
Update CHANGELOG.md
Create git tag
Push gems to RubyGems
Create GitHub release

Getting help

Code of conduct

Be respectful and constructive. We're all here to build something useful.

Be welcoming to newcomers
Respect different viewpoints
Focus on what's best for the project
Show empathy to others