Proxy & Server Commands

Relevant source files

The following files were used as context for generating this wiki page:

• lib/kamal/cli/proxy.rb
• lib/kamal/cli/main.rb
• lib/kamal/commander.rb
• lib/kamal/configuration/validator/proxy.rb
• lib/kamal/configuration/role.rb
• test/commands/proxy_test.rb

Proxy and Server commands in Kamal manage the lifecycle of kamal-proxy and the underlying server infrastructure required to run containerized applications. Kamal uses kamal-proxy to facilitate zero-downtime deploys by seamlessly switching traffic between application containers. The system handles booting the proxy, managing load balancer configurations, and performing health checks to ensure application readiness.

The architecture relies on SSHKit for remote execution and Docker for container management. Server bootstrapping ensures Docker is present, while proxy commands manage the specific routing layer that sits in front of the application roles.

Sources: README.md:3-8, lib/kamal/cli/main.rb:7-12

Kamal Proxy Management

The Kamal::Cli::Proxy class provides the command-line interface for managing the kamal-proxy container. This includes booting the proxy, rebooting it to apply configuration changes, and managing dynamic TLS domains.

Proxy Boot Logic

When booting, Kamal ensures the Docker network exists and then proceeds to log in to the registry. The boot process checks for configuration "drift"—where the running container's configuration digest no longer matches the local deploy configuration. If drift is detected and reboot_on_deploy is enabled, the proxy is automatically rebooted.

The proxy boot process also handles the port_holder architecture, which uses a dedicated container to hold ports during handoffs to achieve zero downtime.

Sources: lib/kamal/cli/proxy.rb:3-64, test/commands/proxy_test.rb:213-239

Proxy Configuration Options

The proxy supports extensive configuration through the deploy.yml file, including SSL settings, health checks, and traffic shaping.

Category	Option	Description
Run	bind_ips	Host IPs to bind HTTP/HTTPS traffic to.
Run	publish	Boolean to enable/disable port publishing.
SSL	ssl_domains	Dynamic TLS domain source and intervals.
Lifecycle	session_affinity	Sticky session configuration via cookies.
Traffic	redirects	Pattern-based URL redirections.

Sources: lib/kamal/configuration/validator/proxy.rb:11-80, lib/kamal/cli/proxy.rb:122-132

Server Bootstrapping and Setup

Server management is primarily handled through the Main CLI class, which orchestrates the initial setup and subsequent deployments.

Initial Setup Flow

The setup command is the entry point for new environments. It bootstraps the servers (installing Docker) before invoking the application deployment sequence.

Readiness Gates

Kamal ensures that servers are ready to receive traffic using readiness gates. For roles running the proxy, this is checked via the proxy's health check. For unproxied roles, Kamal relies on Docker health checks or a simple readiness delay.

Source	Description
proxy	kamal-proxy health check endpoint.
healthcheck	Docker container health check command.
healthcheck_exec	Custom execution probe run from the deploy host.
none	Fallback: container is ready after readiness_delay seconds.

Sources: lib/kamal/configuration/role.rb:142-168

Load Balancer Integration

When a primary role has multiple hosts, Kamal can auto-enable load balancing. The load balancer is essentially a kamal-proxy instance configured to route traffic across multiple target hosts.

Shared Load Balancer Tier

In shared topologies, Kamal manages service ownership to prevent multiple applications from clobbering each other on a shared load balancer host.

• Service Claiming: Kamal records which application owns a service name on the load balancer.
• Config Hashing: The load balancer's run configuration is hashed to ensure all apps using it agree on the proxy settings (e.g., ports, SSL).

Sources: lib/kamal/cli/proxy.rb:78-120, test/cli/proxy_test.rb:436-470

Load Balancer Lifecycle Commands

The kamal proxy loadbalancer subcommand allows for direct management of the load balancer tier.

# Example: Deploying to loadbalancer
# lib/kamal/cli/proxy.rb:358-364
def loadbalancer(status)
  case status
  when "deploy"
    if KAMAL.config.proxy.load_balancing?
      targets = KAMAL.loadbalancer_config.target_hosts
      on(KAMAL.config.proxy.effective_loadbalancer) do |host|
        Kamal::Cli::Proxy::LoadbalancerClaim.new(host, self).claim_service
        execute *KAMAL.loadbalancer.deploy(targets: targets)
      end
    end
  end
end

Sources: lib/kamal/cli/proxy.rb:342-370

Diagnostic and Maintenance Commands

Kamal provides tools to verify the state of proxies and servers.

• kamal proxy details: Captures docker ps info for the proxy container across all hosts. Sources: lib/kamal/cli/proxy.rb:304-311
• kamal proxy logs: Fetches Docker logs from proxy containers, supporting --follow, --since, and --grep. Sources: lib/kamal/cli/proxy.rb:314-335
• kamal doctor: Diagnoses deploy readiness including registry authentication, port availability, and version compatibility. Sources: lib/kamal/cli/main.rb:125-138

Summary

Proxy and Server commands form the backbone of Kamal's routing and infrastructure management. By automating Docker network creation, proxy booting with drift detection, and load balancer orchestration, Kamal provides a robust path for zero-downtime deployments on bare metal or cloud VMs. The system enforces strict validation of configurations (e.g., SSL hosts, IP CIDR ranges, and basic auth) to ensure that the production environment remains stable and secure.