Changelog

odysseus-core

Fixed

• odysseus could not read an SSH key from disk unless ssh-agent happened to be holding it. net-ssh needs ed25519 and bcrypt_pbkdf to parse anything in the -----BEGIN OPENSSH PRIVATE KEY----- container -- which is what every modern ssh-keygen writes, RSA included, not only ed25519 -- and neither was declared, so key_factory.rb raised NotImplementedError before it ever looked at the algorithm. Both are runtime dependencies now. Reported by a tester whose deploys failed with a passphrase-protected key; the passphrase was not the cause, the key format was.

• A passphrase-protected SSH key is no longer reported as "Check your SSH keys." odysseus connects with non_interactive: true -- a passphrase prompt on a deploy connection can never be answered, so prompting would hang rather than help -- and net-ssh reports the resulting key-loading failure to a logger rather than raising it, so with none configured the reason was discarded and the reader was sent to inspect keys that were entirely correct. The failure now names each locked key and gives the ssh-add line for it. Odysseus::SSHKey.encrypted? answers that by reading the cipher named in the key file, so no passphrase is needed to detect one.

• docker pussh no longer hangs silently. It ran through backticks with everything folded into a captured string, which had three consequences: no output reached the terminal until the push finished, so a healthy push and a stuck one looked identical; there was no timeout; and stdin stayed attached to the parent, so a child that asked a question waited forever on an answer nobody could see it requesting. Output now streams as it arrives, stdin is closed so any prompt reaches EOF and fails promptly, and a push is bounded by PUSSH_TIMEOUT (30 minutes -- generous, since it exists to end a hang rather than to police a slow link). A push that does time out now suggests what to check, including the Tailscale steps SSH#with_connection already gives for the deploy connection but which pussh never reached.

Changed

• Every container odysseus starts now has a bounded log. Containers inherited the daemon's default logging, which on a stock Docker install is json-file with no size limit, so a long-lived container filled the disk -- most visibly odysseus-caddy, the one container no deploy ever replaces. Every docker run now carries --log-driver json-file --log-opt max-size=100m --log-opt max-file=3.

  The driver is named rather than left to the daemon because max-size and max-file belong to json-file and local only: on a host defaulting to journald or syslog, docker refuses the run rather than ignoring them. Naming it also makes explicit what odysseus logs already assumed, since it shells out to docker logs.

  This overrides a deliberate daemon-wide log driver on the host. Making the driver and options configurable per service is tracked in TODO.md.

odysseus-cli

Fixed

• deploy --build no longer dies with incompatible character encodings: UTF-8 and BINARY after the build has already succeeded. The streamed-output reader accumulated chunks from IO#read_nonblock, which returns ASCII-8BIT, into a UTF-8 string literal -- which silently takes the chunk's encoding on the first append. Any byte above 0x7F in the build or push output then reached the spinner's UTF-8 format string as binary and raised there. Bytes are now accumulated as binary and decoded once a line is complete, so a read boundary falling inside a multi-byte character cannot mangle it either. Reported from a real deploy that failed while pushing to a host.

odysseus-core

Fixed

• Caddy no longer loses every route when its container is replaced or the host reboots. Routes are added through the admin API and live in Caddy's memory; Caddy autosaves them to $XDG_CONFIG_HOME/caddy/autosave.json, which the official image sets to /config -- and odysseus mounted only /data (XDG_DATA_HOME), so certificates persisted and routes were discarded with the container. On a host with nine services, all nine stayed unreachable until nine separate deploys ran. HostPaths#caddy_config_dir is now mounted at /config and Caddy starts with --resume.

  If --resume fails to start the container, odysseus renames the autosave to autosave.json.rejected and starts once without it. CADDY_IMAGE is the moving caddy:2-alpine tag, so a newer Caddy can meet an autosave it will not parse, and WebDeploy aborts when Caddy does not come up -- unhandled, one bad autosave would have failed every deploy on the host. The rename runs inside a container: Caddy creates /config/caddy as root with mode 0700, so a non-root deploy user cannot move the file from the host.

  A host that has never run Caddy still has no routes until each service deploys; --resume falls back to the image's Caddyfile there, which is what creates srv0.

• Commands echoed under --debug/-v no longer print secrets. SSH#execute echoed the command verbatim, and registry login is built as echo '<password>' | docker login <server> -u <user> --password-stdin -- --password-stdin keeps the password off the argv, and interpolating it into echo put it straight back into the string being echoed. With no -p and no --password, every pattern written to catch those missed it. New Odysseus::CommandRedaction runs on the way to the terminal only; the command executed is unchanged.

odysseus-cli

Changed

• cleanup's documentation now describes what the command does. It was "Clean up old containers and optionally prune images" in both the README and --help; it stops and force-removes every container for the service on that server -- every role and every dependency, databases included, not only old ones and not sparing the container serving traffic -- then removes the service's Caddy routes and, if no other service is left behind the proxy, removes the shared odysseus-caddy container too. No behaviour changed. The name still undersells it; see TODO.md.

odysseus-core

Fixed

• Setup::Escalation's sudo probe no longer reports an unreachable host as a sudo problem. It rescued Odysseus::Error, the shared ancestor of SSHCommandError and SSHConnectionError, and the probe is the first command setup sends — so a host whose name did not resolve was told to configure passwordless sudo. It now catches only the error that means the command ran and sudo refused.

• SSHAuthenticationError is a new class under SSHError, raised where SSHConnectionError was raised for Net::SSH::AuthenticationFailed. "The host refused this identity" and "the host was never reached" were the same class, so no caller could advise on one without guessing about the other. Nothing rescued SSHConnectionError specifically, so no other behaviour changes.

• SSH#with_connection no longer describes a connection that never opened as a mid-command drop. IOError, Net::SSH::Disconnect, ECONNRESET and EPIPE arrive both while opening and while a command runs, and the rescue wrapped both, so a host that accepted the connection and hung up before any command existed — one still booting, or an sshd not yet up — was reported as having dropped a command that had never been sent.

• Docker::Client escapes the healthcheck command instead of wrapping it in hand-written single quotes. A cmd containing a quote, such as --execute='SELECT 1', closed the quote early and word-split into docker's arguments, so the tail landed where the image name goes and docker reported it could not find image '1:latest'. Volume specs are escaped for the same reason. A container's cmd stays unescaped by design — it has to reach the container as separate arguments.

Added

• Odysseus::Setup::Escalation, Odysseus::Setup::PublicKey, Odysseus::Setup::DockerApt and Odysseus::Setup::Preparer, the classes behind odysseus setup (odysseus-cli). Escalation gets root on the target host via passwordless sudo, or none at all when connected as root, and refuses up front — before anything is touched — if passwordless sudo isn't available, since a password prompt can't be answered. PublicKey resolves which key(s) to install, entirely on the local machine before any host is touched: from --key, or from each ssh.keys entry's .pub sibling, deriving one via ssh-keygen -y only when that sibling is empty or missing; a key that doesn't resolve, or a sibling with content that doesn't validate, refuses by name rather than silently substituting a different key. DockerApt installs Docker from Docker's own official apt repository, following Docker's published instructions for Ubuntu: it installs docker-ce docker-ce-cli containerd.io docker-buildx-plugin (Docker's instructions also install docker-compose-plugin, which is deliberately left out — nothing in this codebase invokes docker compose). The keyring and apt sources file are written whole on every run, never appended, so an interrupted run leaves a stale file the next run replaces rather than a corrupt one. apt runs non-interactively with a 300-second bounded wait for the dpkg lock, long enough to outlast cloud-init and unattended-upgrades on a minutes-old host; a timeout names the process holding the lock. It repairs no apt or dpkg state it did not create. The GPG key's fingerprint is deliberately not pinned, matching Docker's own instructions, which trust TLS rather than pin it — pinning would turn Docker's key rotation into an outage for everyone using this command. Preparer runs the actual sequence against a host: installs Docker via DockerApt if the host doesn't already have it, creates the deploy user and its home, adds it to the docker group, installs the resolved key(s), creates the state directory, and finishes by opening a second connection as that new user to prove Docker and the state directory both work before reporting success. A host whose Docker daemon still does not answer after the install is failed, naming that the host may need a reboot or that the daemon may have failed to start — success is decided by the daemon answering after the install runs, not by apt exiting zero.

odysseus-cli

Fixed

• setup names the --as flag when the bootstrap identity cannot authenticate. The default identity is a guess — right on a stock Ubuntu cloud image, wrong on anything else — and the failure was a bare "SSH authentication failed", with nothing to suggest a flag existed that would fix it. A host that is merely unreachable still gets no --as advice.

• --debug (and ODYSSEUS_DEBUG=1) reaches the SSH layer, not only the UI. It was read and passed to the UI, but the connection builders never passed verbose: to SSH.new, so the flag whose purpose is showing what was sent to the host showed nothing for setup, doctor, status, containers or logs. setup accepts -v as well.

Added

• odysseus setup, which prepares every host in the config so odysseus can deploy to it as a non-root user: creates the user ssh.user names, adds it to the docker group, installs your public key, installs Docker itself if the host doesn't have it, and creates its state directory. Connects as --as USER, default ubuntu — the user Ubuntu's LTS cloud images ship with passwordless sudo already configured; --as root needs no sudo. It reads no new configuration keys: the user, keys and hosts all come from the existing ssh.user, ssh.keys and servers.*.hosts, with --key PATH (repeatable) to override the key source. setup no longer refuses a host without Docker — if docker info doesn't answer, it installs Docker from Docker's own apt repository and checks again, and only fails the step if the daemon still doesn't answer afterward — and it still refuses anything other than Ubuntu 24.04 or 26.04 by name. It reports what it changed separately from what was already correct, and finishes by reconnecting as the new user to prove the host actually works before reporting success.

odysseus-core

Fixed

• VersionResolver#resolve now names the deployer for an explicitly-tagged deploy (odysseus deploy --image v1.2.3), instead of recording nil. The deployer comes from git config user.email, falling back to $USER — a lookup that needs no commit and no clean working tree, so withholding it alongside ref was never justified. Every explicitly-tagged deploy wrote a host-side log line with no name on it, which emptied the "by whom" column of odysseus rollback --list and left the host-side deploy history unattributed. ref still stays nil for an explicit tag: an arbitrary tag names no commit it honestly identifies, so there is nothing true to record there.

• Caddy::Client#start_caddy now publishes the admin API on 127.0.0.1:2019 instead of 2019:2019, which bound it to every interface. That API can rewrite the proxy configuration — routes, upstreams, TLS — for every service on the host, so anyone who could reach the port controlled the proxy. Caddy::Client only ever calls it via curl localhost over SSH, so nothing needed the external exposure. The in-container CADDY_ADMIN bind stays 0.0.0.0:2019, which is what the published port maps to — only where the port lands on the host changed. This does not close the exposure on a host where Caddy is already running: ensure_running returns early when the container is up, so the new binding only takes effect the next time Caddy is recreated (stopped and restarted, or removed). An already-running Caddy stays bound to every interface until that happens.

• JobDeploy now ensures the odysseus Docker network exists before starting a container, instead of assuming it. It ran every container with network: 'odysseus' but never created that network itself, so a jobs-only service deployed to a fresh host failed at docker run. The gap was invisible on any host that had ever deployed a web role or a dependency first: a web role's ensure_caddy! creates the network as a side effect of starting Caddy, and DependencyDeploy has always had its own ensure_network!. Found on a genuinely fresh host with the deploy user ready but no prior deploy of either kind.

• Caddy::Client#ensure_running now recreates a stopped Caddy container instead of trying to docker run a new one over it. Once Caddy had been stopped, --name odysseus-caddy collided with the container Docker still had by that name, and docker run refused every time after: every subsequent deploy failed and the proxy stayed down until someone removed the container by hand. Absent and already-running containers are unaffected. The stopped container is removed rather than docker started so it always picks up current configuration — notably the deploy-user Caddy directory added earlier in this file — instead of resuming with whatever it was created with.

Added

• Odysseus::HostPaths, which decides where odysseus keeps state on a host from the connecting SSH user: root still gets /var/lib/odysseus, exactly as before and with no extra SSH round trip; any other user gets $HOME/.odysseus, resolved by asking the host once per connection.

• Odysseus::HostVerifier, a read-only diagnosis of one host, run as the user the config names rather than root. #verify runs distro, docker reachability, docker group membership, state-directory writability and deploy-log location, and returns one Result per check with a :ok, :warn or :fail status — it writes nothing to the host. odysseus doctor (odysseus-cli) drives it over every host in a config.

Changed

• Env files (Docker::Client) and the deploy log (DeployLog) now follow HostPaths instead of a fixed /var/lib/odysseus constant. Before this, a non-root deploy could not work at all: write_env_file chmods its directory before writing into it, and a non-owner cannot chmod a directory root created, so the deploy died at the first container start. This is the change that makes a non-root deploy possible, on a host you have already configured for it.

• Caddy's certificate directory (Caddy::Client) now follows HostPaths too, instead of staying fixed at /var/lib/odysseus/caddy. It was deliberately left out of the earlier change in this release to avoid moving issued Let's Encrypt certificates or re-issuing against rate limits — but that risk only ever applied to root installs, which are the only ones with certificates at the old path. Deriving the directory protects them identically: root still resolves to /var/lib/odysseus/caddy, byte-identical. Leaving it fixed meant a non-root deploy user could never create it, so ensure_running failed at mkdir -p /var/lib/odysseus/caddy on every non-root web deploy — found on a real host. Root is unaffected.

• rollback --list keeps its history across the move: a host that deployed as root and later switches to a deploy user still has its old log read as a fallback when the new location is absent (or unreadable) rather than empty — an empty file at the new location exits 0 and suppresses the fallback. Reads fall back to the old location; appends only ever go to the new one.

• Executor#host_roles is public API now, not a private helper. It answers the same question the CLI needs answered — which hosts does this config target, and which roles does each serve — so odysseus doctor can visit every host once, however many roles it serves, without duplicating the host-resolution logic this method already implements.

• Nothing changes for a root install.

odysseus-cli

Changed

• Requires odysseus-core ~> 0.8.0. The dependency was ~> 0.7.0, which excludes 0.8.0 outright, so this is not a tightening: without it the two gems cannot resolve together. odysseus doctor also calls Odysseus::HostVerifier and Executor#host_roles, neither available in 0.7.0.

Added

• odysseus doctor, a read-only diagnosis of every host in the config, connecting as the user ssh.user names rather than root. It reports distro, docker reachability, docker group membership, state-directory writability and deploy-log location for each host, via Odysseus::HostVerifier (odysseus-core). An unsupported distro is a warning rather than a failure; only a failing check sets a non-zero exit. A host whose check raises — a dropped connection, say — is reported and the survey continues to the rest. doctor changes nothing on the host.

odysseus-core

Fixed

• A one-off container — what app exec, app shell and app console run — no longer has its environment inlined into the docker command as -e KEY=VALUE. Every value now travels in the same 0600 env file a deployed container's does, so a customer's database password is no longer visible in ps on the deploy target, and a value containing a space or a shell metacharacter arrives intact instead of splitting or being interpreted. The file is named so it cannot collide with a running container's, and is removed even when the command fails.

• The env file is removed over a fresh connection when the connection it was written over has died in the meantime. Cleanup rescued Odysseus::SSHError alone, and a connection that drops mid-session raises IOError, Net::SSH::Disconnect, Errno::EPIPE or Errno::ECONNRESET — none of them an SSHError. The cleanup's own failure therefore escaped the ensure and replaced whatever the block was raising, so a file of secrets was left on the host and an interactive session's exit status arrived as a backtrace. The interactive paths are where this is likeliest: they hold the connection open, idle and unpumped, for as long as the user's session lasts, which is what an idle NAT timeout, sshd's ClientAlive limit or a Tailscale relay change need. Any failure of the removal is now swallowed rather than raised — including on the second attempt, after which the file is left behind, 0600 in a 0700 directory.

• An upload that fails partway no longer orphans a partial env file. The path was learned from the return value of the write, so a write that raised left the caller with nil and its cleanup with nothing to remove — while scp had already created the remote file and begun streaming secrets into it. The path is settled before the write now, so the file removed is the file written, whether or not the write finished.

Added

• Odysseus::Core::Environment, the environment a container starts with — env.clear merged with each env.secret resolved from the encrypted secrets file or the host's own environment. WebDeploy and JobDeploy each had their own copy; one-off commands had neither, which is why rails db:migrate on a one-off container started without a DATABASE_URL.

• Docker::Client#with_env_file, which writes an env file, yields its path and removes it afterwards even on failure. app shell and app console need an interactive TTY and so run docker themselves; this is how their environment reaches the host as a file rather than as -e flags.

odysseus-cli

Changed

• Requires odysseus-core ~> 0.7.0. The dependency was ~> 0.6.0, which excludes 0.7.0 outright, so this is not a tightening: without it the two gems cannot resolve together. These commands also call Core::Environment and Docker::Client#with_env_file, neither of which exists in 0.6.0.

• bin/odysseus's dispatch table no longer lists dependency, app and secrets. Their entries named methods the CLI has never had (dependency_dispatch, app_dispatch, secrets_dispatch); the subcommand guards intercept those verbs first, so nothing changes today, but the entries would have turned any reordering of a guard into a NoMethodError backtrace. The suite now runs every verb the help lists.

Fixed

• odysseus app exec|shell|console now inject env.secret as well as env.clear. They injected the clear values alone, so the README's own example — odysseus app exec web1 --command "rails db:migrate" — started a container with no DATABASE_URL while the container deployed seconds earlier had one. Both orchestrators had always injected both; these three never did. The environment is now built by the same Core::Environment the deploy paths use, so a secret resolves from the encrypted file when one is configured and from the host's own environment otherwise, exactly as a deploy resolves it.

• A relative secrets_file is resolved against the directory holding the deploy.yml these commands were pointed at, not the working directory, which is the rule deploys already followed.

• odysseus app shell|console pass the environment to docker with --env-file instead of -e KEY=VALUE. The values were in the command string these commands run over ssh, so ps on the deploy target showed them to every user on the box; now only the file's path is. The file is 0600, is held open for the whole session and is removed when the session ends, however it ends — including when the ssh connection it was written over has died while the session sat idle, which is removed over a fresh connection. Two cases still leave it on the host: the odysseus process being killed outright (SIGKILL, or the machine going down), where no cleanup can run at all, and a host that is unreachable when the session ends, where the removal has nowhere to go. The file is 0600 in /var/lib/odysseus/env, which is 0700, so no other user on the box can read it, but nothing comes back for it. app exec reaches the same place through run_once, which writes an env file of its own — see odysseus-core's changelog.

• odysseus dependency exec|shell are unchanged: they docker exec into an already-running dependency, which carries the environment it was booted with.

• odysseus app exec|shell|console now take --role (default web) and look the container up by the label that role actually carries. They asked for the bare service name, which only the web role wears: on a jobs host they reported No running container for myapp while myapp-jobs containers were running, and for a service with no web role at all they could not work on any host, with no workaround. The app parser had no --role either, so naming one raised an OptionParser::InvalidOption backtrace.

• The not-found message from those commands now names the role, the odysseus.service label it searched for and the --role option, and lists the roles in the config. It does not search other roles: running your command against a role you did not name would be worse than being told what to type.

• odysseus logs gives that same message. A mistyped --role — odysseus logs w1 --role jbos — got No containers found for myapp-jbos on w1 (stopped ones included), naming a label the reader never typed and no way to find the one they wanted. Both commands now share the message rather than keeping two that can drift. odysseus dependency logs gets the label it searched for too, but not the --role advice: a dependency is chosen with --name.

• odysseus logs and odysseus dependency logs read stopped containers as well as running ones. They asked docker ps without -a, so the container that had just exited — the one you want the logs of — was invisible, and they reported No running containers found and exited 0 while docker logs on that container would have worked. Deploys keep the previous two containers, so this was routine rather than an edge case.

• Those two commands now exit non-zero when there is no container at all: a request for logs that produced none is a failed request, not a success. When the only match is stopped they say so, and name the container, rather than streaming a dead container's logs and leaving you to wonder why it ends.

• Both of those messages go to stderr. odysseus logs web1 > app.log is the command most likely to be redirected or piped into something that parses what it gets, and a line about the logs does not belong inside them. The notice still reaches the terminal of whoever ran the command. Every other command writes where it always did.

• odysseus app shell|console and odysseus dependency shell now exit non-zero when the session fails. They discarded system's return value, so a refused ssh, a missing image or a failed docker run all reported success.

• The same three quote what they put in the command they run. Values were interpolated raw into a string that passes through two shells, so ordinary env.clear values broke them: a value containing a space made docker read the wrong token as the image name, and an apostrophe (SMTP_FROM: "Bob's App") unbalanced the quoting — an odd number left sh: unexpected EOF and nothing running (reported as success, per the bug above), an even number rebalanced the quotes and ran the text between them through the local shell. An SSH key path containing a space failed the same way.

• odysseus app console --cmd is split into words the way a shell would, so --cmd "rails c" still reaches docker as two arguments, and a --cmd whose own quoting cannot be read is reported instead of being passed on.

• odysseus app shell|console print a header before handing the terminal over. They printed nothing at all: odysseus app shell dedalus-prod answered with /app $ and no way to tell which host you had reached, which role, or which build you were looking at. app exec has had a header from the start. The new one names the server, the role, the image that is serving and the command the container runs, in the same shape as app exec's.

• It also says the thing a prompt inside a container invites you to assume the other way round: this is a new container started from the serving image, not an attach to the container taking traffic. Nothing done in it reaches the running app and all of it goes when the session ends. odysseus dependency shell is deliberately not given the same line — it docker execs into the running dependency, where the opposite is true.

• That header goes to stderr. odysseus app console web1 --cmd "rails runner 'puts Thing.count'" > count is a reasonable way to read a value out of a deployment, and a header inside that file would be a bug: stdout carries what the session itself produced and nothing else. app exec's header is unchanged, on stdout, where the output of its run_once already is.

odysseus-core

Added

• plugins: in deploy.yml, a list of gem names loaded before the config is validated, so a sail can register its strategy in time for servers.<role>.deploy.strategy to resolve. sails: is accepted as an alias. Until now nothing ever loaded a sail: both registries raised "is the gem loaded?" for every user, so deploy.strategy and the aws: host hook were unreachable while both READMEs described them.

• Odysseus::Core::DeployVersioning, the shared container version identity — odysseus.version, odysseus.git_ref and odysseus.deployed_at — included by both built-in orchestrators and available to sails. status, rollback and image retention all read these labels, so an orchestrator that invents its own scheme is invisible to them.

Changed

• A deploy.yml carrying both plugins: and sails:, or both dependencies: and accessories:, is now an error. Silently preferring one meant editing the wrong key had no visible effect.

• odysseus validate loads plugins, so it now catches a plugin gem that is not installed. It will fail on a machine without the gem, where it passed before.

• A plugin that fails to load now reports the file that was actually missing, and says so differently when the plugin itself was found. A sail whose own dependency is absent — odysseus-sail-aws-asg without aws-sdk-autoscaling — used to read as if the sail were not installed, advising an install that could not fix it. The advice also names the Gemfile, which is what a bundle exec odysseus run needs.

• Plugin errors quote the key the deploy.yml actually used. Writing sails: and getting told about plugins: named a key that was not in the file.

odysseus-cli

Changed

• odysseus validate now loads plugins:/sails: before checking the rest of the config, so it catches a plugin gem that is not installed instead of only discovering the gap at deploy time. It will fail on a machine that does not have the gem, where it passed before. See odysseus-core's changelog for the loading mechanism itself.

• Requires odysseus-core ~> 0.6.0. The dependency was ~> 0.5.0, which excludes 0.6.0 outright, so the two gems could not resolve together at all.

• The README documents dynamic ASG hosts again, now that plugins: makes them reachable. The example it previously carried could not have parsed: it showed an aws: role with no hosts: key, which every role requires.

odysseus-core

Added

• retain_versions in deploy.yml, default 5: how many distinct versions of a service's image each host keeps. After a successful deploy, images beyond that window are removed from the host. Until now SHA-tagged images accumulated without limit — cleanup --prune-images only removes dangling images, and a tagged image is never dangling.

• RetentionPlanner, Docker::Client#remove_image and Docker::Client#versions_in_use.

Changed

• deploy prunes old images on each host once all of that host's roles are deployed. rollback deliberately does not: deleting images during a recovery is the wrong moment, and the version just rolled back from is the most likely next thing wanted.

  Three independent things must agree before an image is deleted: it must fall outside the retain window, no container on the host may reference it (stopped containers included, since a stopped container still references its image and an operator may still need it), and docker must accept the removal. Each removal is attempted on its own, so one refusal is a logged skip rather than a failed deploy. A host with no deploys.log is skipped entirely rather than pruned by image creation time, which is build time and can be out of order. latest is never removed automatically.

odysseus-cli

Changed

• Requires odysseus-core ~> 0.5.0. The previous ~> 0.4.4 constraint excludes 0.5.0 outright, so this is not a tightening but a necessary move: without it the two gems cannot resolve together at all.

• odysseus deploy now prunes old images on each host, keeping the newest retain_versions (default 5). See odysseus-core's changelog for what is protected from removal.

odysseus-core

Changed

• accessories: in deploy.yml is now dependencies:. The old name implied optional extras, when a database the app cannot boot without is not optional. The old key is still accepted and parses identically, so existing deploy.yml files keep working; it will be removed in a later release.

• Nothing on a host changes as a result. Container names and the odysseus.service label are built from the service name plus the individual dependency's name, so the top-level key never reaches a host and running containers are adopted rather than orphaned. A spec runs the real parser over a legacy fixture and asserts the resulting container name, so this cannot regress silently.

• Orchestrator::AccessoryDeploy is Orchestrator::DependencyDeploy, Deployer::AccessoryManager is Deployer::DependencyManager, and Executor's six accessory methods are now deploy_dependency, remove_dependency, restart_dependency, upgrade_dependency, dependency_status and boot_dependencies. No deprecated aliases: nothing outside odysseus-cli consumes these, and the two gems ship in lockstep.

• The config error messages changed accordingly: Dependency 'x' not found in config and No hosts configured for dependency x.

Internal

• Config::Parser#parse_accessories and its two helpers are now parse_dependencies, parse_dependency_healthcheck and parse_dependency_proxy. The parser gained its first coverage for this block in the process.

odysseus-cli

Changed

• Requires odysseus-core ~> 0.4.4. The dependency was ~> 0.4.3, which allowed installing a core whose Executor still named its six methods deploy_accessory, boot_accessories and so on — all of which the dependency commands call under their new names, so they would have failed with a NoMethodError rather than a resolvable error.

• odysseus accessory is now odysseus dependency, with dep accepted as shorthand. The old verb still works and prints a notice naming the replacement, because a silent alias never gets migrated away from; it will be removed in a later release. The accessories: key in deploy.yml is likewise now dependencies:, with the old key still accepted — see odysseus-core's changelog for why nothing on a host changes when you rename it.

• Help text, subcommand output and the Dependency name required error read "dependency" throughout.

odysseus-core

Added

• Executor#rollback_plan and #rollback_all, which return every role on every host to a previously deployed version by reusing the deploy path, so health gating and proxy handling are shared with deploy. The target is chosen from what the hosts report — running container labels, images present, and each host's deploys.log — never from the local repository, which can drift from what a host can actually run.

• A fleet pre-flight: the target image must be present on every host across all roles before any host is touched. A half-rolled-back fleet is worse than a refused command.

• Executor#version_survey, HostVersions and RollbackPlanner.

• Docker::Client#image_tags, listing the tags a host has for a repository.

Changed

• Deploys are recorded on the host by Executor rather than by each orchestrator. A rollback now records kind=rolled-back with the version it replaced, and a role deployed by a sail-provided strategy gets the same audit trail instead of none.

• VersionResolver#deployer is public, so a rollback can name who ran it even though its version came from a host rather than a commit.

Fixed

• odysseus accessory status never worked in any released version. The code called orchestrator.get_status(name:), but Orchestrator::AccessoryDeploy defines list_status and no get_status, so the command always raised NoMethodError. The bad call was introduced on 2025-12-27 in 343030b, three days before the accessory status subcommand itself shipped in odysseus-cli 0.2.0 (2025-12-30) — so there was never a working version to regress from. Fixed in 188a695: AccessoryManager#status_on now calls list_status and selects the requested accessory out of its results, and a new spec exercises it through a verifying double, so a future rename of list_status breaks the build instead of the command.

Internal

• Accessory lifecycle methods (deploy, remove, restart, upgrade, status, boot_all) moved out of Executor into Deployer::AccessoryManager, to keep both classes under their existing size limits. The public API is unchanged, and AccessoryManager gets the first spec coverage that code has ever had.

odysseus-cli

Added

• odysseus rollback [VERSION], returning every role on every host to a previously deployed version. With no VERSION, the target is the most recent version in the hosts' deploy logs that is not already serving and whose image is still present everywhere. Refuses, changing nothing, when any host lacks the image.

• odysseus rollback --list, showing per host: every version deployed, when, by whom, from which commit, whether the image is still present, and what is serving. Reads only the hosts, so it works without a git repository.

Changed

• Requires odysseus-core ~> 0.4.3. The dependency was ~> 0.4.2, which allowed installing a core without Executor#rollback_plan, #rollback_all or #version_survey — all of which rollback calls, so the command would have failed with a NoMethodError rather than a resolvable error.

Fixed

• odysseus accessory status now works. It has raised NoMethodError since before the subcommand shipped in 0.2.0; see odysseus-core's changelog for the root cause and fix.

Internal

• Rollback commands moved out of the main CLI class into Odysseus::CLI::RollbackCommands, to keep the class under its existing size limit without changing its public API.

odysseus-core

Added

• The image tag now defaults to the git commit being deployed, and containers carry odysseus.version, odysseus.deployed_at and odysseus.git_ref labels, so a running container can be traced to a commit. odysseus.version previously held the deploy timestamp, which odysseus.deployed_at now carries.

• Each host records successful deploys in /var/lib/odysseus/<service>/deploys.log.

Changed

• deploy, build and pussh no longer default to the latest tag. Outside a git repository, or with uncommitted changes, they stop and ask for --image. The version resolves before the dry-run check, so --dry-run also requires a resolvable version even though it makes no changes.

odysseus-cli

Changed

• deploy, build and pussh no longer default --image to the latest tag; the tag now defaults to the git commit being deployed, and is required outside a clean git repository.

• status reports the version, ref and deploy time of each container.

• app exec, app shell and app console run the version that is currently serving instead of :latest.

• Requires odysseus-core ~> 0.4.2. The dependency was ~> 0.4, which allowed installing a core without Executor#deploy_version or Docker::Labels — both of which these commands now call, so deploy would have failed with a NoMethodError rather than a resolvable error.

odysseus-core

Fixed

• Caddy::Client#enable_tls_for_hosts updates an existing tls app in place instead of trying to recreate it. Caddy's PUT creates and answers 409 if the key is already there, so on any host whose Caddy already had a tls app this call had always failed and the policy update had always been discarded — a domain added to proxy.hosts after the first deploy never got a policy and so never got an ACME account email. Certificates still arrived through Caddy's implicit automation, which is why it went unnoticed. 0.4.0 did not break this; it stopped hiding it.

• The new policy is merged onto the existing tls config rather than replacing it, so sibling settings — explicit certificate loaders, on_demand limits — survive a deploy.

odysseus-core

Fixed

• Deployer::SSH#execute reads the channel's exit status and raises SSHCommandError on a non-zero exit. Previously every remote command appeared to succeed, so a failed docker stop, docker rm, mkdir or network create was invisible.

• Deployer::SSH#execute no longer merges stderr into its return value, so callers parsing stdout are not handed warning text. This also repairs Docker::Client#health_status for containers with no Health block.

• Caddy::Client raises ProxyApiError when a mutating admin API request fails. curl exits 0 for HTTP errors, so a rejected route write was parsed as an ordinary response and discarded — the deploy reported success while no traffic was routed. Reads still return nil, as Caddy answers 500 for config paths that do not exist yet.

• Orchestrator::WebDeploy aborts when Caddy fails to start. The result of ensure_running was discarded and the guard clause that raises had become dead code.

• A web container is always given a health command, defaulting to GET / on proxy.app_port. Without a healthcheck block — the shape both READMEs show — the container had no health command, its status stayed none, and every deploy timed out after 60s and rolled back. A web role with no app_port now fails fast with a config error.

• Docker::Client#wait_healthy honours the timeout it is passed instead of capping every wait at 60s, so the 120s requested by JobDeploy and AccessoryDeploy is respected.

• Caddy::Client#add_upstream reconciles a route's Host matcher, so editing proxy.hosts takes effect instead of requiring the route to be removed by hand.

Changed

• Container environment is passed through a 0600 env file under /var/lib/odysseus/env and --env-file, instead of -e KEY=VALUE on the command line. Secrets no longer appear in the host's process list, and values containing spaces or shell metacharacters survive intact. A value containing a newline is rejected rather than silently truncated.

• Licensed under MIT. The gemspec and LICENSE previously said LGPL-3.0-only while the READMEs said MIT.

Removed

• The unused Odysseus::VERSION constant, stale at 0.1.0. Odysseus::Core::VERSION is the single source of truth.

Internal

• validators/config.rb and sails.rb are covered by specs for the first time.

• rake runs RSpec and RuboCop clean. Remaining Metrics offences are recorded in .rubocop_todo.yml rather than hidden in the main configuration.

odysseus-cli

Added

• odysseus version and --version, reporting the CLI, odysseus-core and ruby versions. Answered before any config is loaded, so it works without a deploy.yml or a reachable server.

• Odysseus::CLI::VERSION, so the gem version has one source of truth instead of being hardcoded in the gemspec.

• A test suite: RSpec, .rspec and a rake default task. Argument dispatch and exit codes are covered by running the real executable in a subprocess, the commands are unit-tested against a doubled executor, and the redaction of secrets from streamed output is pinned.

• RuboCop, sharing odysseus-core's configuration.

Changed

• Requires odysseus-core ~> 0.4. The dependency was ~> 0.2, which allowed installing a core old enough to lack the deploy fixes the CLI relies on.

• Requires Ruby >= 3.2.0, matching odysseus-core. The gemspec asked for >= 3.0, which could not have worked.

• Licensed under MIT. The gemspec previously said LGPL-3.0-only while the README said MIT.

• CLEAN_MESSAGES is a private_constant; it sat after a private modifier, which does nothing for constants.

• Development dependencies live in the Gemfile only, as in odysseus-core; the gemspec declared rspec and pry-byebug a second time.

Fixed

• The gem now ships its license file. spec.files looked for LICENSE while the file is LICENSE.txt, so published gems contained no license text.

Removed

• The ratatui_ruby dependency. Nothing in the CLI required or referenced it — it pulled a native extension into every install for nothing.

• Documentation for Charm mode (--charm, ODYSSEUS_CHARM=1, gum), removed from the code in 0.3.0 but left in the README, and for AWS Auto Scaling Group hosts, which moved to a sail gem nothing currently loads.

odysseus-core

Fixed

• Adding a hostname to proxy.hosts had no effect on an already-deployed service. Caddy::Client#add_upstream reconciled only the upstreams of an existing route, never its Host matcher, so the route kept whatever hosts it was created with until it was deleted by hand. TLS was unaffected -- enable_tls_for_hosts always received the full list -- which made the failure confusing: Caddy answered the new hostname over HTTPS with a valid certificate, matched no route, and served the default handler instead of the service. add_upstream now PATCHes match/0/host when the configured hosts differ from the deployed ones. The repair needs one deploy: the reconcile runs during add_upstream, so upgrading alone leaves an existing route as it was.

odysseus-core

Fixed

• Ruby 4.0 compatibility: declare the logger dependency explicitly.

Removed

• The AWS Auto Scaling Group host provider, extracted to odysseus-sail-aws-asg. HostProviders keeps the registry and the aws: config hook the sail consumes.

odysseus-core

Added

• Sails plugin registry, with the rolling deploy strategy extracted to odysseus-sail-rolling. servers.<role>.deploy.strategy resolves through it.

• Volume namespacing: named volumes are prefixed with the service name so containers sharing a host no longer collide, reusing an existing un-namespaced volume rather than losing data.

• Docker::Client#ensure_network, so accessories can boot before any service deploy has created the network.

• Parsing for servers.<role>.containers and servers.<role>.deploy, including timeouts and an HTTP health check with a success threshold.

odysseus-cli

Changed

• Rewrote terminal output as numbered steps with animated spinners resolving to ✓/✗, rendered by CLI::UI, replacing the gum-backed Charm mode. --debug (or ODYSSEUS_DEBUG=1) switches to verbose plain text.

• Secret values are redacted from streamed output via RedactingIO.

odysseus-core

Added

• Encrypted secrets files (AES-256-GCM) with Secrets::EncryptedFile and Secrets::Loader.

• Builder with local and remote (build host) strategies, plus pussh distribution over SSH for registry-less deploys.

• Host provider registry behind HostProviders, with the static provider as the default.

• CPU and memory limits for containers.

odysseus-cli

Added

• Charm TUI mode (--charm, ODYSSEUS_CHARM=1) built on gum, for styled headers, spinners, tables and confirmations. Superseded in 0.3.0.

• secrets subcommands: generate-key, encrypt, decrypt, edit.

• accessory subcommands: boot, boot-all, remove, restart, upgrade, status, logs, exec, shell.

• pussh command for pushing images to hosts over SSH without a registry.

odysseus-core

• Initial release: config parsing, SSH and Docker clients, Caddy proxy integration with automatic TLS, web and job orchestrators, and the accessory lifecycle.

odysseus-cli

• Initial release: deploy, build, status, containers, logs, cleanup, validate, and the app subcommands.