App & Containers Commands

Relevant source files

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

• lib/kamal/cli/app.rb
• lib/kamal/commands/app.rb
• lib/kamal/commands/app/containers.rb
• lib/kamal/cli/main.rb
• lib/kamal/configuration.rb

Introduction

The "App & Containers Commands" suite in Kamal provides the core functionality for managing application lifecycles across remote servers. This includes booting new versions, starting and stopping existing containers, executing ad-hoc commands, and performing canary rollouts. These commands leverage Docker for containerization and kamal-proxy for zero-downtime traffic switching.

The system is designed to handle multi-role deployments (e.g., web and workers) across multiple hosts, ensuring that environment variables, assets, and SSL certificates are correctly provisioned before application code is executed. It works in conjunction with Registry Commands for image management and Proxy Commands for traffic routing.

Sources: lib/kamal/cli/app.rb:1-5, README.md

Lifecycle Management

Kamal manages the application lifecycle through high-level CLI commands that orchestrate multiple low-level Docker operations and hook executions.

Boot Sequence

The boot command is the primary method for deploying or rebooting an application. It follows a strict sequence:

1. Preparation: Ensures error pages, assets, and SSL certificates are present on the host.
2. Hook Execution: Runs pre-app-boot hooks.
3. Execution: Starts containers in groups defined by the boot.limit configuration, respecting parallel_roles settings.
4. Post-Boot: Runs post-app-boot hooks and tags the new image as latest.

Rollout Management

Canary rollouts allow a new version to run alongside the live version. The rollout command supports actions to deploy the target, set traffic percentages or cookie-based lists, and stop the rollout.

Action	Description	Key Configuration
deploy	Boots the rollout version alongside the live version.	Uses version_or_latest.
set	Updates kamal-proxy to split traffic.	--percent or --list.
stop	Removes the rollout target and restores full traffic to live.	N/A

Sources: lib/kamal/cli/app.rb:227-258, lib/kamal/commands/app.rb:122-132

Container Operations

Container commands provide direct access to Docker container states and metadata. These are implemented via the Kamal::Commands::App::Containers module.

Core Container Functions

• list_containers: Lists all containers filtered by service and destination.
• remove_containers: Prunes old containers using Docker's container prune.
• container_health_log: Inspects the health status of a specific container version.
• rename_container: Facilitates versioning by renaming existing containers.

Stale Container Detection

The stale_containers command identifies containers that are not the currently running version. If the --stop flag is provided, Kamal will automatically halt these containers to free up resources.
Sources: lib/kamal/cli/app.rb:147-164

Command Execution

The exec command allows running arbitrary commands inside application containers. It supports two main modes: starting a new container for the command or reusing an existing running container.

Execution Options

• Interactive (-i): Launches the command over SSH with a TTY, suitable for consoles or bash sessions.
• Reuse (--reuse): Executes the command inside the currently running container via docker exec.
• Detached (--detach): Runs the command in the background.
• Raw (--raw): Returns unmodified stdout from the remote server.

Configuration and Filtering

Commands are scoped using labels and filters to ensure they only affect the intended service and role.

Filter	Logic	Implementation
Service	label=service=[service_name]	Kamal::Commands::App#container_filters
Destination	label=destination=[dest]	Kamal::Commands::App#container_filters
Role	label=role=[role_name]	Kamal::Commands::App#container_filters
Status	status=running, status=restarting	ACTIVE_DOCKER_STATUSES

Sources: lib/kamal/commands/app.rb:4-6, lib/kamal/commands/app.rb:92-105

Conclusion

The App & Containers commands form the operational backbone of Kamal. By combining orchestrated boot sequences with granular container controls and flexible execution options, Kamal provides a robust environment for managing containerized web applications. The heavy reliance on Docker labels ensures that even in complex multi-role environments, commands remain precise and safe.