odysseus-core 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 917c4ba0f885774f77c2bb74ce396300be9f9ae077f5ddc8d54bd96e4766d6d8
-  data.tar.gz: ea50eb29cd561fa1ae3de2f6f81df06d33f4cb21bd4a36f3a0a60acc94cfd0f4
+  metadata.gz: 1a525389c6d10cc9400d5b1f0b5fa053bd446b5239cd7894d02e1ee829b71bdb
+  data.tar.gz: ed2314a392b04d987a3e6ca18a544b9ad40810f41b7a78cd7a045908bab00433
 SHA512:
-  metadata.gz: 1eef3bc36f17dce94de204c1b4ddec3bdbc9f2d3882ec2dc2b7fd56cfe90f56a53856c8bcfb90df3ee10dce4e9236f5a748efc7b7b88d5babea919a02f636772
-  data.tar.gz: 2a3b7d72b6ddbc2e6210839e803a8c9173d41d952775695dea80a1172a919d22308f40e17b0f79ae37668d0b7f109b1e4591b3445ea0fab2a47cde8b9e570caa
+  metadata.gz: 101e926f2178d3e8467d07eb375170de61c99b038f42ea61f9041eeb8dc7e6227e18eba407e592383b8ce626dcdd9590a506200a863eb07b0c216d57ccd9349b
+  data.tar.gz: bb11c66ef05c4d809bda9abb486d2dd1871d8be2ba9b17520f1b528f49339fafa1b25cd933d18a520f2022ad80442fb5d321f53581d32281d9c074177e79c012

data/README.md

@@ -1,43 +1,88 @@
-# Odysseus::Core
+# Odysseus Core
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/odysseus/core`. To experiment with that code, run `bin/console` for an interactive prompt.
+Core library for [Odysseus](https://github.com/WA-Systems-EU/odysseus), a zero-downtime Docker deployment tool with Caddy reverse proxy integration.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
-Install the gem and add to the application's Gemfile by executing:
-
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install odysseus-core
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or add to your Gemfile:
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem 'odysseus-core'
 ```
 
+## Overview
+
+Odysseus Core provides the foundational components for Docker container deployment:
+
+- **Configuration parsing** - YAML-based deploy.yml configuration
+- **Docker client** - Container lifecycle management via SSH
+- **Caddy client** - Reverse proxy configuration and routing
+- **Deployer** - Zero-downtime deployment orchestration
+- **Secrets** - Encrypted secrets file support
+
 ## Usage
 
-TODO: Write usage instructions here
+This gem is primarily used by [odysseus-cli](https://rubygems.org/gems/odysseus-cli). For direct usage:
 
-## Development
+```ruby
+require 'odysseus'
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+# Parse configuration
+parser = Odysseus::Config::Parser.new('deploy.yml')
+config = parser.parse
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# Create executor
+executor = Odysseus::Deployer::Executor.new('deploy.yml')
 
-## Contributing
+# Deploy
+executor.deploy_all(image_tag: 'v1.0.0')
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/odysseus-core. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/odysseus-core/blob/trunk/CODE_OF_CONDUCT.md).
+## Components
 
-## License
+### Odysseus::Config::Parser
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Parses deploy.yml configuration files with support for:
+- Server roles (web, jobs, workers)
+- Proxy configuration (Caddy)
+- Accessories (databases, Redis, etc.)
+- Environment variables and secrets
+- AWS Auto Scaling Group integration
 
-## Code of Conduct
+### Odysseus::Docker::Client
+
+Docker operations via SSH:
+- Container lifecycle (run, stop, remove)
+- Image management
+- Health checks
+- Log streaming
+
+### Odysseus::Caddy::Client
+
+Caddy reverse proxy management:
+- Dynamic upstream configuration
+- Zero-downtime routing updates
+- TLS certificate management
+
+### Odysseus::Deployer::Executor
+
+Deployment orchestration:
+- Build and distribute images
+- Zero-downtime container replacement
+- Health check verification
+- Automatic rollback on failure
+
+### Odysseus::Secrets::EncryptedFile
+
+Encrypted secrets management:
+- AES-256-GCM encryption
+- Environment variable injection
+- Secure key management
+
+## License
 
-Everyone interacting in the Odysseus::Core project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/odysseus-core/blob/trunk/CODE_OF_CONDUCT.md).
+LGPL-3.0-only

data/lib/odysseus/config/parser.rb

@@ -65,11 +65,48 @@ module Odysseus
             options: symbolize_keys(config['options'] || {}),
             cmd: config['cmd'],
             volumes: config['volumes'],
-            healthcheck: parse_server_healthcheck(config['healthcheck'])
+            healthcheck: parse_server_healthcheck(config['healthcheck']),
+            containers: parse_containers(config['containers']),
+            deploy: parse_deploy(config['deploy'])
           }
         end
       end
 
+      # Parse containers config (for multi-container per host)
+      def parse_containers(containers)
+        return nil unless containers
+
+        {
+          count: containers['count'] || 1,
+          name_pattern: containers['name_pattern']
+        }
+      end
+
+      # Parse deploy strategy config
+      def parse_deploy(deploy)
+        return nil unless deploy
+
+        {
+          strategy: deploy['strategy']&.to_sym,
+          drain_timeout: deploy['drain_timeout'] || 30,
+          stop_timeout: deploy['stop_timeout'] || 10,
+          boot_timeout: deploy['boot_timeout'] || 60,
+          health_check: parse_deploy_health_check(deploy['health_check'])
+        }
+      end
+
+      # Parse deploy-level health check (HTTP polling with threshold)
+      def parse_deploy_health_check(hc)
+        return nil unless hc
+
+        {
+          path: hc['path'] || '/up',
+          interval: hc['interval'] || 2,
+          threshold: hc['threshold'] || 3,
+          timeout: hc['timeout'] || 5
+        }
+      end
+
       # Parse AWS host provider config
       # @param aws [Hash] aws block from server config
       # @return [Hash, nil] normalized aws config or nil

data/lib/odysseus/core/version.rb

@@ -2,6 +2,6 @@
 
 module Odysseus
   module Core
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/odysseus/core/volume_namespacer.rb

@@ -0,0 +1,77 @@
+# lib/odysseus/core/volume_namespacer.rb
+
+module Odysseus
+  module Core
+    module VolumeNamespacer
+      # Namespace volumes to avoid conflicts when multiple apps share a server.
+      #
+      # Named volumes (no leading /) get prefixed with the service name:
+      #   "data:/var/lib/postgresql/data" → "myapp-data:/var/lib/postgresql/data"
+      #
+      # Host path volumes (leading /) are left as-is — the user owns the path.
+      #
+      # When a named volume is being namespaced, we check if the old (un-namespaced)
+      # volume already exists on the server. If it does, we reuse it to avoid data loss
+      # and log a deprecation warning.
+      #
+      # @param volumes [Array<String>, nil] volume specs (e.g. ["data:/container/path"])
+      # @param service [String] service name used as prefix
+      # @return [Array<String>, nil] namespaced volume specs
+      def namespace_volumes(volumes, service:)
+        return nil unless volumes
+
+        volumes.map { |v| namespace_volume(v, service: service) }
+      end
+
+      private
+
+      def namespace_volume(volume_spec, service:)
+        host_part, container_part, mode = volume_spec.split(':')
+
+        # Host path mount (absolute path) — user controls the path, leave as-is
+        return volume_spec if host_part.start_with?('/')
+
+        # Already namespaced — don't double-prefix
+        return volume_spec if host_part.start_with?("#{service}-")
+
+        namespaced = "#{service}-#{host_part}"
+
+        # Check if we need to handle migration from old volume name
+        if docker_volume_exists?(namespaced)
+          # New namespaced volume already exists — use it
+          return build_volume_spec(namespaced, container_part, mode)
+        end
+
+        if docker_volume_exists?(host_part)
+          # Old un-namespaced volume exists but new one doesn't.
+          # Reuse the old volume to avoid data loss, and warn the user.
+          log "Volume '#{host_part}' exists but is not namespaced. Reusing it to avoid data loss.", :warn
+          log "  To migrate, run: docker volume create #{namespaced} && " \
+              "docker run --rm -v #{host_part}:/from -v #{namespaced}:/to alpine sh -c 'cp -a /from/. /to/'", :warn
+          return volume_spec
+        end
+
+        # Neither exists — use the new namespaced name (fresh deploy)
+        build_volume_spec(namespaced, container_part, mode)
+      end
+
+      def build_volume_spec(host_part, container_part, mode)
+        parts = [host_part, container_part]
+        parts << mode if mode
+        parts.join(':')
+      end
+
+      def docker_volume_exists?(name)
+        return false unless respond_to?(:docker_client, true)
+
+        docker_client.volume_exists?(name)
+      rescue StandardError
+        false
+      end
+
+      def docker_client
+        @docker
+      end
+    end
+  end
+end

data/lib/odysseus/core.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "core/version"
+require_relative "core/volume_namespacer"
 
 module Odysseus
   module Core

data/lib/odysseus/deployer/executor.rb

@@ -315,7 +315,16 @@ module Odysseus
 
       def build_orchestrator(ssh, role)
         logger = build_logger
-        if role == WEB_ROLE
+        role_config = @config[:servers][role] || {}
+        strategy = role_config.dig(:deploy, :strategy)
+
+        # Check if a sail plugin provides this strategy
+        if strategy && Odysseus::Sails.registered?(strategy)
+          sail_klass = Odysseus::Sails.resolve(strategy)
+          sail_klass.new(
+            ssh: ssh, config: @config, logger: logger, secrets_loader: @secrets_loader
+          )
+        elsif role == WEB_ROLE
           Odysseus::Orchestrator::WebDeploy.new(
             ssh: ssh, config: @config, logger: logger, secrets_loader: @secrets_loader
           )

data/lib/odysseus/docker/client.rb

@@ -254,6 +254,22 @@ module Odysseus
         results
       end
 
+      # Check if a Docker named volume exists
+      # @param name [String] volume name
+      # @return [Boolean]
+      def volume_exists?(name)
+        output = @ssh.execute("docker volume inspect #{name} 2>/dev/null && echo 'yes' || echo 'no'")
+        output.strip.end_with?('yes')
+      end
+
+      # Ensure a Docker network exists, creating it if missing
+      # @param name [String] network name
+      # @param labels [Hash] labels to apply when creating
+      def ensure_network(name, labels: {})
+        label_flags = labels.map { |k, v| "--label #{k}=#{v}" }.join(' ')
+        @ssh.execute("docker network inspect #{name} >/dev/null 2>&1 || docker network create #{label_flags} #{name}".strip)
+      end
+
       # Get disk usage info
       # @return [String] docker system df output
       def disk_usage

data/lib/odysseus/host_providers.rb

@@ -6,8 +6,7 @@ module Odysseus
       # Registry of available host providers
       def providers
         @providers ||= {
-          static: Static,
-          aws_asg: AwsAsg
+          static: Static
         }
       end
 
@@ -15,14 +14,14 @@ module Odysseus
       # @param role_config [Hash] role configuration from deploy.yml
       # @return [Base] host provider instance
       def build(role_config)
-        if role_config[:aws]
-          # AWS ASG provider
-          AwsAsg.new(role_config[:aws])
+        if role_config[:aws] && providers[:aws_asg]
+          providers[:aws_asg].new(role_config[:aws])
+        elsif role_config[:aws]
+          raise Odysseus::ConfigError,
+                "AWS ASG host provider not available — is the odysseus-sail-aws-asg gem loaded?"
         elsif role_config[:hosts]
-          # Static hosts (default)
           Static.new(hosts: role_config[:hosts])
         else
-          # No hosts configured
           Static.new(hosts: [])
         end
       end

data/lib/odysseus/orchestrator/accessory_deploy.rb

@@ -1,8 +1,12 @@
 # lib/odysseus/orchestrator/accessory_deploy.rb
 
+require_relative '../core/volume_namespacer'
+
 module Odysseus
   module Orchestrator
     class AccessoryDeploy
+      include Odysseus::Core::VolumeNamespacer
+
       # @param ssh [Odysseus::Deployer::SSH] SSH connection
       # @param config [Hash] parsed deploy config
       # @param secrets_loader [Odysseus::Secrets::Loader] secrets loader (optional)
@@ -27,42 +31,53 @@ module Odysseus
         image = accessory_config[:image]
 
         log "Deploying accessory: #{service_name}"
+        log "  Image: #{image}"
+
+        # Ensure the Docker network exists (accessories may boot before any service deploy)
+        ensure_network!
 
         # Check if accessory is already running
         existing = @docker.list(service: service_name)
         if existing.any? { |c| c['State'] == 'running' }
-          log "Accessory #{service_name} is already running"
+          log "  Already running — skipping"
           return { success: true, already_running: true, service: service_name }
         end
 
         # Start the accessory
         log "Starting #{service_name}..."
         container_id = start_accessory(name: name, config: accessory_config)
-        log "Started container: #{container_id[0..11]}"
+        log "  Container started: #{container_id[0..11]}"
 
         # Wait for healthy if healthcheck configured
         if accessory_config[:healthcheck]
-          log "Waiting for container to be healthy..."
+          hc = accessory_config[:healthcheck]
+          log "Waiting for health check... (cmd: #{hc[:cmd]}, interval: #{hc[:interval]}s)"
           unless @docker.wait_healthy(container_id, timeout: 120)
+            log_health_failure(container_id)
             @docker.stop(container_id)
             @docker.remove(container_id, force: true)
             raise Odysseus::DeployError, "Accessory failed health checks"
           end
-          log "Container is healthy!"
+          log "  Health check passed"
         else
+          log "No health check configured, waiting 3s for startup..."
           sleep 3
           unless @docker.running?(container_id)
+            log_health_failure(container_id)
             raise Odysseus::DeployError, "Accessory failed to start"
           end
+          log "  Container is running"
         end
 
         # Add to Caddy if proxy config is present
         if accessory_config[:proxy]
-          log "Configuring proxy..."
+          proxy_hosts = accessory_config[:proxy][:hosts]&.join(', ')
+          log "Configuring proxy (hosts: #{proxy_hosts})..."
           add_to_caddy(name: name, container_id: container_id, config: accessory_config)
+          log "  Proxy configured"
         end
 
-        log "Accessory #{service_name} deployed!"
+        log "Accessory #{service_name} deployed"
 
         {
           success: true,
@@ -71,7 +86,7 @@ module Odysseus
           image: image
         }
       rescue StandardError => e
-        log "Accessory deploy failed: #{e.message}", :error
+        log "Accessory deploy FAILED: #{e.message}", :error
         raise
       end
 
@@ -122,12 +137,16 @@ module Odysseus
         service_name = accessory_name(name)
         image = accessory_config[:image]
 
-        log "Upgrading accessory: #{service_name} to #{image}"
+        log "Upgrading accessory: #{service_name}"
+        log "  Image: #{image}"
+
+        # Ensure the Docker network exists
+        ensure_network!
 
         # Pull the new image first (before stopping anything)
-        log "Pulling new image: #{image}..."
+        log "Pulling new image..."
         @docker.pull(image)
-        log "Image pulled successfully"
+        log "  Image pulled"
 
         # Check for existing container
         existing = @docker.list(service: service_name, all: true)
@@ -137,46 +156,54 @@ module Odysseus
         if accessory_config[:proxy] && old_container && old_container['State'] == 'running'
           container_name = old_container['Names'].delete_prefix('/')
           port = accessory_config[:proxy][:app_port]
-          log "Removing from proxy..."
+          log "Draining from proxy..."
           @caddy.drain_upstream(service: service_name, upstream: "#{container_name}:#{port}")
+          log "  Drained from proxy"
         end
 
         # Stop and remove old container if exists
         if old_container
-          log "Stopping old container: #{old_container['ID'][0..11]}..."
+          log "Stopping old container #{old_container['ID'][0..11]} (30s grace period)..."
           @docker.stop(old_container['ID'], timeout: 30) if old_container['State'] == 'running'
           @docker.remove(old_container['ID'], force: true)
-          log "Old container removed"
+          log "  Old container removed"
         end
 
         # Start the accessory with the new image (volumes are preserved on host)
-        log "Starting new container with #{image}..."
+        log "Starting new container..."
         container_id = start_accessory(name: name, config: accessory_config)
-        log "Started container: #{container_id[0..11]}"
+        log "  Container started: #{container_id[0..11]}"
 
         # Wait for healthy if healthcheck configured
         if accessory_config[:healthcheck]
-          log "Waiting for container to be healthy..."
+          hc = accessory_config[:healthcheck]
+          log "Waiting for health check... (cmd: #{hc[:cmd]}, interval: #{hc[:interval]}s)"
           unless @docker.wait_healthy(container_id, timeout: 120)
+            log_health_failure(container_id)
             @docker.stop(container_id)
             @docker.remove(container_id, force: true)
             raise Odysseus::DeployError, "Accessory failed health checks after upgrade"
           end
-          log "Container is healthy!"
+          log "  Health check passed"
         else
+          log "No health check configured, waiting 3s for startup..."
           sleep 3
           unless @docker.running?(container_id)
+            log_health_failure(container_id)
             raise Odysseus::DeployError, "Accessory failed to start after upgrade"
           end
+          log "  Container is running"
         end
 
         # Add to Caddy if proxy config is present
         if accessory_config[:proxy]
-          log "Configuring proxy..."
+          proxy_hosts = accessory_config[:proxy][:hosts]&.join(', ')
+          log "Configuring proxy (hosts: #{proxy_hosts})..."
           add_to_caddy(name: name, container_id: container_id, config: accessory_config)
+          log "  Proxy configured"
         end
 
-        log "Accessory #{service_name} upgraded to #{image}!"
+        log "Accessory #{service_name} upgraded"
 
         {
           success: true,
@@ -217,17 +244,34 @@ module Odysseus
         "#{@config[:service]}-#{name}"
       end
 
+      def ensure_network!
+        log "Ensuring Docker network exists..."
+        @docker.ensure_network('odysseus', labels: { 'odysseus.managed' => 'true' })
+      end
+
       def start_accessory(name:, config:)
         service_name = accessory_name(name)
 
+        env = build_environment(config[:env])
+        log "  Environment: #{env.size} variable(s) injected" if env.any?
+
+        volumes = namespace_volumes(config[:volumes], service: service_name)
+        if volumes&.any?
+          log "  Volumes: #{volumes.join(', ')}"
+        end
+
+        if config[:ports]&.any?
+          log "  Ports: #{config[:ports].join(', ')}"
+        end
+
         @docker.run(
           name: service_name,
           image: config[:image],
           options: {
             service: service_name,
-            env: build_environment(config[:env]),
+            env: env,
             ports: config[:ports],
-            volumes: config[:volumes],
+            volumes: volumes,
             network: 'odysseus',
             restart: 'unless-stopped',
             healthcheck: build_healthcheck(config[:healthcheck]),
@@ -293,6 +337,27 @@ module Odysseus
         )
       end
 
+      def log_health_failure(container_id)
+        log "Health check FAILED for container #{container_id[0..11]}", :error
+
+        begin
+          recent_logs = @docker.logs(container_id, tail: 30)
+          unless recent_logs.strip.empty?
+            log "  Container logs (last 30 lines):", :error
+            recent_logs.each_line { |line| log "    #{line.rstrip}", :error }
+          end
+        rescue StandardError => e
+          log "  Could not fetch container logs: #{e.message}", :warn
+        end
+
+        begin
+          status = @docker.health_status(container_id)
+          log "  Health status: #{status}", :error
+        rescue StandardError
+          # ignore
+        end
+      end
+
       def default_logger
         @default_logger ||= Object.new.tap do |l|
           def l.info(msg); puts msg; end

data/lib/odysseus/orchestrator/job_deploy.rb

@@ -1,8 +1,12 @@
 # lib/odysseus/orchestrator/job_deploy.rb
 
+require_relative '../core/volume_namespacer'
+
 module Odysseus
   module Orchestrator
     class JobDeploy
+      include Odysseus::Core::VolumeNamespacer
+
       # @param ssh [Odysseus::Deployer::SSH] SSH connection
       # @param config [Hash] parsed deploy config
       # @param logger [Object] logger (optional)
@@ -24,46 +28,54 @@ module Odysseus
         role_name = "#{service}-#{role}"
         image = "#{@config[:image]}:#{image_tag}"
 
-        log "Starting deploy of #{role_name} with #{image}"
+        log "Deploying #{role_name}"
+        log "  Image: #{image}"
+
+        server_config = @config[:servers][role] || {}
+        log "  Command: #{server_config[:cmd]}" if server_config[:cmd]
 
         # Step 1: Find existing containers for this role
-        log "Checking for existing containers..."
         old_containers = @docker.list(service: role_name)
-        log "Found #{old_containers.size} existing container(s)"
+        log "  Found #{old_containers.size} existing container(s)"
 
         # Step 2: Start new container
         log "Starting new container..."
         new_container_id = start_new_container(image: image, role: role)
-        log "Started container: #{new_container_id[0..11]}"
+        log "  Container started: #{new_container_id[0..11]}"
 
         # Step 3: Wait for healthy (if healthcheck configured)
-        server_config = @config[:servers][role] || {}
         if server_config[:healthcheck]
-          log "Waiting for container to be healthy..."
+          hc = server_config[:healthcheck]
+          log "Waiting for health check... (cmd: #{hc[:cmd]}, interval: #{hc[:interval]}s)"
           unless wait_for_healthy(new_container_id)
+            log_health_failure(new_container_id)
             handle_failed_deploy(new_container_id)
             raise Odysseus::DeployError, "Container failed health checks"
           end
-          log "Container is healthy!"
+          log "  Health check passed"
         else
-          # No healthcheck - just wait a few seconds for startup
-          log "No healthcheck configured, waiting for startup..."
+          log "No health check configured, waiting 5s for startup..."
           sleep 5
           unless @docker.running?(new_container_id)
+            log_health_failure(new_container_id)
             handle_failed_deploy(new_container_id)
             raise Odysseus::DeployError, "Container failed to start"
           end
+          log "  Container is running"
         end
 
         # Step 4: Stop old containers gracefully
         old_containers.each do |old|
-          log "Stopping old container: #{old['ID'][0..11]}..."
+          log "Stopping old container #{old['ID'][0..11]} (30s grace period)..."
           graceful_stop(old['ID'])
+          log "  Old container removed"
         end
 
         # Step 5: Cleanup old stopped containers
-        log "Cleaning up old containers..."
-        @docker.cleanup_old_containers(service: role_name, keep: 2)
+        cleaned = @docker.cleanup_old_containers(service: role_name, keep: 2)
+        log "  Cleaned up #{cleaned.size} old container(s)" if cleaned.any?
+
+        log "Deploy complete for #{role_name}"
 
         {
           success: true,
@@ -72,7 +84,7 @@ module Odysseus
           image: image
         }
       rescue StandardError => e
-        log "Deploy failed: #{e.message}", :error
+        log "Deploy FAILED: #{e.message}", :error
         raise
       end
 
@@ -87,13 +99,26 @@ module Odysseus
         server_config = @config[:servers][role] || {}
         options = server_config[:options] || {}
 
+        env = build_environment
+        log "  Environment: #{env.size} variable(s) injected"
+
+        volumes = namespace_volumes(server_config[:volumes], service: role_name)
+        if volumes&.any?
+          log "  Volumes: #{volumes.join(', ')}"
+        end
+
+        if options[:memory] || options[:cpus]
+          log "  Resources: memory=#{options[:memory] || 'default'}, cpus=#{options[:cpus] || 'default'}"
+        end
+
         @docker.run(
           name: container_name,
           image: image,
           options: {
             service: role_name,
             version: timestamp,
-            env: build_environment,
+            env: env,
+            volumes: volumes,
             memory: options[:memory],
             memory_reservation: options[:memory_reservation],
             cpus: options[:cpus],
@@ -157,7 +182,28 @@ module Odysseus
         log "Rolling back failed deploy...", :warn
         @docker.stop(new_container_id)
         @docker.remove(new_container_id, force: true)
-        log "Rollback complete"
+        log "Rollback complete — failed container removed"
+      end
+
+      def log_health_failure(container_id)
+        log "Health check FAILED for container #{container_id[0..11]}", :error
+
+        begin
+          recent_logs = @docker.logs(container_id, tail: 30)
+          unless recent_logs.strip.empty?
+            log "  Container logs (last 30 lines):", :error
+            recent_logs.each_line { |line| log "    #{line.rstrip}", :error }
+          end
+        rescue StandardError => e
+          log "  Could not fetch container logs: #{e.message}", :warn
+        end
+
+        begin
+          status = @docker.health_status(container_id)
+          log "  Health status: #{status}", :error
+        rescue StandardError
+          # ignore
+        end
       end
 
       def default_logger

data/lib/odysseus/orchestrator/web_deploy.rb

@@ -1,8 +1,12 @@
 # lib/odysseus/orchestrator/web_deploy.rb
 
+require_relative '../core/volume_namespacer'
+
 module Odysseus
   module Orchestrator
     class WebDeploy
+      include Odysseus::Core::VolumeNamespacer
+
       # @param ssh [Odysseus::Deployer::SSH] SSH connection
       # @param config [Hash] parsed deploy config
       # @param logger [Object] logger (optional)
@@ -24,48 +28,59 @@ module Odysseus
         service = @config[:service]
         image = "#{@config[:image]}:#{image_tag}"
 
-        log "Starting deploy of #{service} with #{image}"
+        log "Deploying #{service} (role: #{role})"
+        log "  Image: #{image}"
 
         # Step 1: Ensure Caddy is running
         log "Ensuring Caddy proxy is running..."
-        ensure_caddy!
+        if @caddy.running?
+          log "  Caddy already running"
+        else
+          @caddy.ensure_running
+          log "  Caddy started"
+        end
 
         # Step 2: Find existing containers
-        log "Checking for existing containers..."
         old_containers = @docker.list(service: service)
-        log "Found #{old_containers.size} existing container(s)"
+        log "  Found #{old_containers.size} existing container(s)"
 
         # Step 3: Start new container
         log "Starting new container..."
         new_container_id = start_new_container(image: image, role: role)
-        log "Started container: #{new_container_id[0..11]}"
+        log "  Container started: #{new_container_id[0..11]}"
 
         # Step 4: Wait for healthy
-        log "Waiting for container to be healthy..."
+        healthcheck_desc = describe_healthcheck(@config[:proxy]&.dig(:healthcheck))
+        log "Waiting for health check... #{healthcheck_desc}"
         unless wait_for_healthy(new_container_id)
+          log_health_failure(new_container_id)
           handle_failed_deploy(new_container_id, old_containers)
           raise Odysseus::DeployError, "Container failed health checks"
         end
-        log "Container is healthy!"
+        log "  Health check passed"
 
         # Step 5: Add new container to Caddy
-        log "Adding container to Caddy..."
+        proxy_hosts = @config[:proxy][:hosts]&.join(', ')
+        log "Adding to Caddy proxy (hosts: #{proxy_hosts})..."
         add_to_caddy(new_container_id)
+        log "  Caddy routing configured"
 
         # Step 6: Remove old containers from Caddy and stop them
         old_containers.each do |old|
-          log "Draining old container: #{old['ID'][0..11]}..."
+          log "Draining old container #{old['ID'][0..11]}..."
           drain_and_remove(old['ID'])
+          log "  Old container removed"
         end
 
         # Step 7: Cleanup old stopped containers
-        log "Cleaning up old containers..."
-        @docker.cleanup_old_containers(service: service, keep: 2)
+        cleaned = @docker.cleanup_old_containers(service: service, keep: 2)
+        log "  Cleaned up #{cleaned.size} old container(s)" if cleaned.any?
 
         # Step 8: Cleanup stale Caddy upstreams (in case any were missed)
-        log "Cleaning up stale Caddy routes..."
         removed_upstreams = @caddy.cleanup_stale_upstreams(service: service)
-        log "Removed #{removed_upstreams.size} stale upstream(s)" if removed_upstreams.any?
+        log "  Removed #{removed_upstreams.size} stale upstream(s)" if removed_upstreams.any?
+
+        log "Deploy complete for #{service}"
 
         {
           success: true,
@@ -74,7 +89,7 @@ module Odysseus
           image: image
         }
       rescue StandardError => e
-        log "Deploy failed: #{e.message}", :error
+        log "Deploy FAILED: #{e.message}", :error
         raise
       end
 
@@ -95,6 +110,18 @@ module Odysseus
         options = server_config[:options] || {}
         proxy_config = @config[:proxy] || {}
 
+        env = build_environment
+        log "  Environment: #{env.size} variable(s) injected"
+
+        volumes = namespace_volumes(server_config[:volumes], service: service)
+        if volumes&.any?
+          log "  Volumes: #{volumes.join(', ')}"
+        end
+
+        if options[:memory] || options[:cpus]
+          log "  Resources: memory=#{options[:memory] || 'default'}, cpus=#{options[:cpus] || 'default'}"
+        end
+
         @docker.run(
           name: container_name,
           image: image,
@@ -102,8 +129,8 @@ module Odysseus
             service: service,
             version: timestamp,
             ports: internal_port_mapping(proxy_config[:app_port]),
-            env: build_environment,
-            volumes: server_config[:volumes],
+            env: env,
+            volumes: volumes,
             memory: options[:memory],
             memory_reservation: options[:memory_reservation],
             cpus: options[:cpus],
@@ -234,7 +261,41 @@ module Odysseus
         @docker.remove(new_container_id, force: true)
 
         # Old containers should still be running and in Caddy
-        log "Rollback complete - old containers still serving traffic"
+        if old_containers.any?
+          log "Rollback complete — #{old_containers.size} old container(s) still serving traffic"
+        else
+          log "Rollback complete — no previous containers to fall back to", :warn
+        end
+      end
+
+      def log_health_failure(container_id)
+        log "Health check FAILED for container #{container_id[0..11]}", :error
+
+        # Fetch recent container logs to help diagnose the failure
+        begin
+          recent_logs = @docker.logs(container_id, tail: 30)
+          unless recent_logs.strip.empty?
+            log "  Container logs (last 30 lines):", :error
+            recent_logs.each_line { |line| log "    #{line.rstrip}", :error }
+          end
+        rescue StandardError => e
+          log "  Could not fetch container logs: #{e.message}", :warn
+        end
+
+        # Show the health check status
+        begin
+          status = @docker.health_status(container_id)
+          log "  Health status: #{status}", :error
+        rescue StandardError
+          # ignore
+        end
+      end
+
+      def describe_healthcheck(hc_config)
+        return "(no health check configured)" unless hc_config && hc_config[:path]
+
+        port = @config[:proxy][:app_port]
+        "(GET http://localhost:#{port}#{hc_config[:path]}, interval: #{hc_config[:interval] || 10}s)"
       end
 
       def default_logger

data/lib/odysseus/sails.rb

@@ -0,0 +1,44 @@
+# lib/odysseus/sails.rb
+
+module Odysseus
+  module Sails
+    class << self
+      # Registry of available deploy strategy plugins (sails)
+      def strategies
+        @strategies ||= {}
+      end
+
+      # Register a deploy strategy
+      # @param name [Symbol] strategy name (e.g., :rolling)
+      # @param klass [Class] orchestrator class
+      def register(name, klass)
+        strategies[name.to_sym] = klass
+      end
+
+      # Look up a registered strategy
+      # @param name [Symbol] strategy name
+      # @return [Class, nil] orchestrator class or nil
+      def resolve(name)
+        strategies[name.to_sym]
+      end
+
+      # Check if a strategy is registered
+      # @param name [Symbol] strategy name
+      # @return [Boolean]
+      def registered?(name)
+        strategies.key?(name.to_sym)
+      end
+
+      # List all registered strategy names
+      # @return [Array<Symbol>]
+      def available
+        strategies.keys
+      end
+
+      # Reset registry (for testing)
+      def reset!
+        @strategies = {}
+      end
+    end
+  end
+end

data/lib/odysseus/validators/config.rb

@@ -38,6 +38,9 @@ module Odysseus
           raise Odysseus::ConfigValidationError,
                 "server role '#{role}' must have 'hosts' array" \
                 unless config.is_a?(Hash) && config['hosts'].is_a?(Array)
+
+          validate_containers!(role, config['containers']) if config['containers']
+          validate_deploy!(role, config['deploy']) if config['deploy']
         end
       end
 
@@ -68,6 +71,36 @@ module Odysseus
         end
       end
 
+      def validate_containers!(role, containers)
+        return unless containers.is_a?(Hash)
+
+        count = containers['count']
+        if count && (!count.is_a?(Integer) || count < 1)
+          raise Odysseus::ConfigValidationError,
+                "servers.#{role}.containers.count must be an integer >= 1"
+        end
+      end
+
+      def validate_deploy!(role, deploy)
+        return unless deploy.is_a?(Hash)
+
+        strategy = deploy['strategy']
+        if strategy && !Odysseus::Sails.registered?(strategy.to_sym)
+          raise Odysseus::ConfigValidationError,
+                "servers.#{role}.deploy.strategy '#{strategy}' is not registered — is the sail plugin gem loaded?"
+        end
+
+        %w[drain_timeout stop_timeout boot_timeout].each do |key|
+          val = deploy[key]
+          next unless val
+
+          unless val.is_a?(Integer) && val > 0
+            raise Odysseus::ConfigValidationError,
+                  "servers.#{role}.deploy.#{key} must be a positive integer"
+          end
+        end
+      end
+
       def validate_ssh!
         ssh = @config['ssh']
         return if ssh.nil?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: odysseus-core
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Thomas
@@ -83,17 +83,18 @@ files:
 - lib/odysseus/config/parser.rb
 - lib/odysseus/core.rb
 - lib/odysseus/core/version.rb
+- lib/odysseus/core/volume_namespacer.rb
 - lib/odysseus/deployer/executor.rb
 - lib/odysseus/deployer/ssh.rb
 - lib/odysseus/docker/client.rb
 - lib/odysseus/errors.rb
 - lib/odysseus/host_providers.rb
-- lib/odysseus/host_providers/aws_asg.rb
 - lib/odysseus/host_providers/base.rb
 - lib/odysseus/host_providers/static.rb
 - lib/odysseus/orchestrator/accessory_deploy.rb
 - lib/odysseus/orchestrator/job_deploy.rb
 - lib/odysseus/orchestrator/web_deploy.rb
+- lib/odysseus/sails.rb
 - lib/odysseus/secrets/encrypted_file.rb
 - lib/odysseus/secrets/loader.rb
 - lib/odysseus/validators/config.rb

data/lib/odysseus/host_providers/aws_asg.rb

@@ -1,91 +0,0 @@
-# lib/odysseus/host_providers/aws_asg.rb
-
-module Odysseus
-  module HostProviders
-    # AWS Auto Scaling Group host provider
-    # Resolves hosts from EC2 instances in an ASG
-    #
-    # Config options:
-    #   asg: ASG name (required)
-    #   region: AWS region (required)
-    #   use_private_ip: Use private IP instead of public (default: false)
-    #   state: Only include instances in this lifecycle state (default: InService)
-    #
-    # AWS credentials are loaded from standard AWS credential chain:
-    #   - Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
-    #   - Shared credentials file (~/.aws/credentials)
-    #   - IAM instance profile (when running on EC2)
-    class AwsAsg < Base
-      def initialize(config)
-        super
-        @asg_name = config[:asg]
-        @region = config[:region]
-        @use_private_ip = config[:use_private_ip] || false
-        @lifecycle_state = config[:state] || 'InService'
-
-        validate_config!
-      end
-
-      # @return [Array<String>] list of instance IPs/hostnames
-      def resolve
-        require_aws_sdk!
-
-        instances = fetch_asg_instances
-        instances.map { |i| extract_address(i) }.compact
-      end
-
-      def name
-        "aws_asg(#{@asg_name})"
-      end
-
-      private
-
-      def validate_config!
-        raise Odysseus::ConfigError, "AWS ASG provider requires 'asg' name" unless @asg_name
-        raise Odysseus::ConfigError, "AWS ASG provider requires 'region'" unless @region
-      end
-
-      def require_aws_sdk!
-        require 'aws-sdk-autoscaling'
-        require 'aws-sdk-ec2'
-      rescue LoadError
-        raise Odysseus::ConfigError,
-          "AWS SDK not installed. Add 'aws-sdk-autoscaling' and 'aws-sdk-ec2' to your Gemfile."
-      end
-
-      def fetch_asg_instances
-        asg_client = Aws::AutoScaling::Client.new(region: @region)
-        ec2_client = Aws::EC2::Client.new(region: @region)
-
-        # Get instance IDs from ASG
-        asg_response = asg_client.describe_auto_scaling_groups(
-          auto_scaling_group_names: [@asg_name]
-        )
-
-        asg = asg_response.auto_scaling_groups.first
-        raise Odysseus::ConfigError, "ASG '#{@asg_name}' not found" unless asg
-
-        # Filter by lifecycle state
-        instance_ids = asg.instances
-          .select { |i| i.lifecycle_state == @lifecycle_state }
-          .map(&:instance_id)
-
-        return [] if instance_ids.empty?
-
-        # Get instance details from EC2
-        ec2_response = ec2_client.describe_instances(instance_ids: instance_ids)
-
-        ec2_response.reservations.flat_map(&:instances)
-      end
-
-      def extract_address(instance)
-        if @use_private_ip
-          instance.private_ip_address
-        else
-          # Prefer public IP, fall back to private
-          instance.public_ip_address || instance.private_ip_address
-        end
-      end
-    end
-  end
-end