### Setup Kamal Deployment

Source: https://github.com/basecamp/kamal-site/blob/main/docs/installation/index.md

Executes the initial setup for Kamal deployment. This process includes connecting to servers via SSH, installing Docker if necessary, logging into the container registry, building and pushing the Docker image, pulling the image onto servers, starting the application container, and configuring traffic routing.

```shell
kamal setup
```

--------------------------------

### Perform Initial Kamal Setup

Source: https://context7.com/basecamp/kamal-site/llms.txt

Executes the `kamal setup` command for the first-time deployment on fresh servers. This includes installing Docker, configuring the proxy, building and deploying the application, and routing traffic.

```bash
# Full setup: installs Docker, configures proxy, builds and deploys app
kamal setup

# Output shows each step:
# 1. Connect to servers over SSH
# 2. Install Docker on servers missing it
# 3. Log into registry locally and remotely
# 4. Build image using Dockerfile
# 5. Push image to registry
# 6. Pull image onto servers
# 7. Start kamal-proxy on ports 80/443
# 8. Start app container
# 9. Route traffic once health check passes
# 10. Prune old images and containers
```

--------------------------------

### Example: Booting All Kamal Accessories

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/accessory.md

This example demonstrates the process of booting all accessory services using the 'kamal accessory boot all' command. It includes output showing pre-connect hooks, lock acquisition, and the Docker command executed to start a busybox accessory.

```bash
$ kamal accessory boot all
Running the pre-connect hook...
  INFO [bd04b11b] Running /usr/bin/env .kamal/hooks/pre-connect on localhost
  INFO [bd04b11b] Finished in 0.003 seconds with exit status 0 (successful).
  INFO [681a028b] Running /usr/bin/env mkdir -p .kamal on server2
  INFO [e3495d1d] Running /usr/bin/env mkdir -p .kamal on server1
  INFO [e7c5c159] Running /usr/bin/env mkdir -p .kamal on server3
  INFO [e3495d1d] Finished in 0.170 seconds with exit status 0 (successful).
  INFO [681a028b] Finished in 0.182 seconds with exit status 0 (successful).
  INFO [e7c5c159] Finished in 0.185 seconds with exit status 0 (successful).
  INFO [83153af3] Running /usr/bin/env mkdir -p .kamal/locks on server1
  INFO [83153af3] Finished in 0.028 seconds with exit status 0 (successful).
Acquiring the deploy lock...
  INFO [416a654c] Running docker login registry:4443 -u [REDACTED] -p [REDACTED] on server1
  INFO [3fb56559] Running docker login registry:4443 -u [REDACTED] -p [REDACTED] on server2
  INFO [3fb56559] Finished in 0.065 seconds with exit status 0 (successful).
  INFO [416a654c] Finished in 0.080 seconds with exit status 0 (successful).
  INFO [2705083f] Running docker run --name custom-busybox --detach --restart unless-stopped --log-opt max-size="10m" --env-file .kamal/env/accessories/custom-busybox.env --label service="custom-busybox" registry:4443/busybox:1.36.0 sh -c 'echo "Starting busybox..."; trap exit term; while true; do sleep 1; done' on server2
  INFO [3cb3adb6] Running docker run --name custom-busybox --detach --restart unless-stopped --log-opt max-size="10m" --env-file .kamal/env/accessories/custom-busybox.env --label service="custom-busybox" registry:4443/busybox:1.36.0 sh -c 'echo "Starting busybox..."; trap exit term; while true; do sleep 1; done' on server1
  INFO [3cb3adb6] Finished in 0.552 seconds with exit status 0 (successful).
  INFO [2705083f] Finished in 0.566 seconds with exit status 0 (successful).
Releasing the deploy lock...

```

--------------------------------

### Install Dependencies and Serve Jekyll Site Locally

Source: https://github.com/basecamp/kamal-site/blob/main/README.md

This snippet installs the necessary Ruby gems for the Jekyll site and then serves the site locally with live reloading enabled. It assumes you have Bundler installed. The site will be accessible at http://localhost:4000.

```bash
bundle install
bundle exec jekyll serve --livereload
```

--------------------------------

### Specify Custom Dockerfile and Context (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

These examples demonstrate how to specify a different Dockerfile or build context when building images. This is useful in monorepo setups or when using multiple Dockerfiles.

```yaml
# Use a different Dockerfile
builder:
  dockerfile: Dockerfile.xyz
```

```yaml
# Set context
builder:
  context: ".."
```

```yaml
# Set Dockerfile and context
builder:
  dockerfile: "../Dockerfile.xyz"
  context: ".."
```

--------------------------------

### Install Dependencies with Private Repo Access Token

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

Installs project dependencies using Bundler, allowing access to private repositories via a GITHUB_TOKEN. It then removes the bundle cache to clean up the image.

```dockerfile
RUN --mount=type=secret,id=GITHUB_TOKEN \
  BUNDLE_GITHUB__COM=x-access-token:$(cat /run/secrets/GITHUB_TOKEN) \
  bundle install && \
  rm -rf /usr/local/bundle/cache
```

--------------------------------

### Install Kamal Gem

Source: https://github.com/basecamp/kamal-site/blob/main/docs/installation/index.md

Installs the Kamal gem globally on your system. This requires a pre-existing Ruby environment. Once installed, Kamal can be run directly from the command line.

```shell
gem install kamal
```

--------------------------------

### Initialize Kamal Configuration

Source: https://github.com/basecamp/kamal-site/blob/main/docs/installation/index.md

Initializes Kamal within your application directory by creating a `config/deploy.yml` file. This file is then edited to specify service details, image, servers, registry credentials, builder architecture, and environment variables.

```yaml
service: hey
image: 37s/hey
servers:
  - 192.168.0.1
  - 192.168.0.2
registry:
  username: registry-user-name
  password:
    - KAMAL_REGISTRY_PASSWORD
builder:
  arch: amd64
env:
  secret:
    - RAILS_MASTER_KEY
```

--------------------------------

### Install and Initialize Kamal

Source: https://context7.com/basecamp/kamal-site/llms.txt

Installs Kamal globally using RubyGems and initializes a new project structure, creating essential configuration files like `config/deploy.yml` and `.kamal/secrets`.

```bash
# Install Kamal globally
gem install kamal

# Initialize Kamal in your project directory
kamal init

# This creates:
# - config/deploy.yml (main configuration)
# - .kamal/secrets (secrets file)
# - .kamal/hooks/ (deployment hooks directory)
```

--------------------------------

### Bootstrap Docker on Servers with Kamal

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/server.md

Sets up Docker on your hosts using `kamal server bootstrap`. It checks for existing Docker installations and attempts to install it via `get.docker.com` if not found. This command is essential for preparing your servers to run Kamal applications.

```bash
$ kamal server bootstrap
```

--------------------------------

### Deploy Kamal Application

Source: https://github.com/basecamp/kamal-site/blob/main/docs/installation/index.md

Performs subsequent deployments of the application using Kamal. This command is used after the initial `kamal setup` and assumes Docker is already installed on the servers. It handles image building, pushing, pulling, and container orchestration.

```shell
kamal deploy
```

--------------------------------

### Set up Docker Buildx and GitHub Runtime for Cache (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

These GitHub Actions workflow snippets show how to set up Docker Buildx and expose the GitHub runtime, which is necessary for enabling GHA cache for Docker builds.

```yaml
- name: Set up Docker Buildx for cache
  uses: docker/setup-buildx-action@v3
```

```yaml
- name: Expose GitHub Runtime for cache
  uses: crazy-max/ghaction-github-runtime@v3
```

--------------------------------

### Example Kamal Configuration for Environment Variables

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/environment-variables.md

This example demonstrates a comprehensive configuration of environment variables in Kamal, including clear values, secrets, and tagged variables for different host groups. It showcases how to manage various types of environment configurations within a single file.

```yaml
env:
  clear:
    MYSQL_USER: app
  secret:
    - MYSQL_PASSWORD
  tags:
    monitoring:
      MYSQL_USER: monitoring
    replica:
      clear:
        MYSQL_USER: readonly
      secret:
        - READONLY_PASSWORD
```

--------------------------------

### Accessory Configuration in deploy.yml

Source: https://context7.com/basecamp/kamal-site/llms.txt

Example configuration for defining accessories such as databases and caches within the deploy.yml file. Supports volumes, environment variables, custom commands, and deployment-specific options.

```yaml
# config/deploy.yml
accessories:
  mysql:
    image: mysql:8.0
    host: db-server.example.com
    port: "127.0.0.1:3306:3306"
    env:
      clear:
        MYSQL_ROOT_HOST: '%'
      secret:
        - MYSQL_ROOT_PASSWORD
    directories:
      - mysql-data:/var/lib/mysql
    files:
      - config/mysql/my.cnf:/etc/mysql/my.cnf:ro
    options:
      restart: always
      cpus: 2
      memory: 4g
    labels:
      app: myapp-db

  redis:
    image: redis:7-alpine
    roles:
      - web
    port: "127.0.0.1:6379:6379"
    directories:
      - redis-data:/data
    cmd: "redis-server --appendonly yes"
```

--------------------------------

### Configure Build Arguments for New Images

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

Demonstrates how to configure build arguments for new images using a YAML configuration. These arguments can then be utilized within the Dockerfile to specify versions or other build-time parameters.

```yaml
builder:
  args:
    RUBY_VERSION: 3.2.0
```

```dockerfile
ARG RUBY_VERSION
FROM ruby:$RUBY_VERSION-slim as base
```

--------------------------------

### Kamal Registry CLI Help

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/registry.md

Displays the available subcommands for the 'kamal registry' command. This includes 'help', 'login', 'logout', 'remove', and 'setup'.

```bash
$ kamal registry
Commands:
  kamal registry help [COMMAND]  # Describe subcommands or one specific subcommand
  kamal registry login           # Log in to remote registry locally and remotely
  kamal registry logout          # Log out of remote registry locally and remotely
  kamal registry remove          # Remove local registry or log out of remote registry locally and remotely
  kamal registry setup           # Setup local registry or log in to remote registry locally and remotely
```

--------------------------------

### Configure Deployment Secrets

Source: https://github.com/basecamp/kamal-site/blob/main/docs/installation/index.md

Sets up environment variables for registry password and Rails master key. The registry password is read directly from the environment, while the Rails master key is read from a local file, typically `config/master.key`.

```shell
KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
RAILS_MASTER_KEY=$(cat config/master.key)
```

--------------------------------

### Kamal Registry Login Example

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/registry.md

Demonstrates the process of logging into a Docker registry using the 'kamal registry login' command. It shows the execution of 'docker login' on multiple servers and the successful completion.

```bash
$ kamal registry login
  INFO [60171eef] Running docker login registry:4443 -u [REDACTED] -p [REDACTED] on localhost
  INFO [60171eef] Finished in 0.069 seconds with exit status 0 (successful).
  INFO [427368d0] Running docker login registry:4443 -u [REDACTED] -p [REDACTED] on server1
  INFO [4c4ab467] Running docker login registry:4443 -u [REDACTED] -p [REDACTED] on server3
  INFO [f985bed4] Running docker login registry:4443 -u [REDACTED] -p [REDACTED] on server2
  INFO [427368d0] Finished in 0.232 seconds with exit status 0 (successful).
  INFO [f985bed4] Finished in 0.234 seconds with exit status 0 (successful).
  INFO [4c4ab467] Finished in 0.245 seconds with exit status 0 (successful).
```

--------------------------------

### Install Kamal 1.9.x using RubyGems

Source: https://github.com/basecamp/kamal-site/blob/main/docs/upgrading/overview.md

Installs version 1.9.0 of the Kamal gem. This version is recommended for in-place upgrades as it includes downgrade support.

```bash
gem install kamal --version 1.9.0
```

--------------------------------

### Configure Remote Builder for Multi-Architecture (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

This configuration enables multi-architecture image building. Kamal builds the architecture matching the deployment server locally and other architectures remotely. Useful for developing on ARM64 and deploying to AMD64.

```yaml
builder:
  arch:
    - amd64
    - arm64
  remote: ssh://root@192.168.0.1
```

--------------------------------

### Manage Application Containers with Kamal App

Source: https://context7.com/basecamp/kamal-site/llms.txt

Provides subcommands for managing running application containers, including viewing details, logs, executing commands, setting maintenance mode, starting, stopping, and rebooting containers.

```bash
# View all app subcommands
kamal app

# Show detailed container info
kamal app details

# View application logs
kamal app logs

# Follow logs in real-time
kamal app logs --follow

# Execute command on all servers
kamal app exec 'ruby -v'

# Execute command on primary server only
kamal app exec --primary 'cat .ruby-version'

# Run Rails console interactively
kamal app exec -i 'bin/rails console'

# Start bash session in running container
kamal app exec -i --reuse bash

# Run database migrations
kamal app exec --primary 'bin/rails db:migrate'

# Set app to maintenance mode
kamal app maintenance --message "Scheduled maintenance, back soon"

# Return app to live mode
kamal app live

# Stop app containers
kamal app stop

# Start stopped containers
kamal app start

# Reboot app (stop, remove, start fresh)
kamal app boot
```

--------------------------------

### Configure Local Builder for Single Architecture (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

This configuration ensures that Kamal always builds images locally for a single specified architecture using a local buildx instance.

```yaml
builder:
  arch: amd64
```

--------------------------------

### Build Image with Cloud Native Buildpacks (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

This configuration demonstrates building an application image using Cloud Native Buildpacks instead of a Dockerfile. It specifies the builder image and buildpacks to use, such as Heroku's Ruby and Procfile buildpacks.

```yaml
pack:
  builder: heroku/builder:24
  buildpacks:
    - heroku/ruby
    - heroku/procfile
```

--------------------------------

### Upgrade Specific Hosts with Kamal

Source: https://github.com/basecamp/kamal-site/blob/main/docs/upgrading/overview.md

Allows upgrading specific hosts by providing their IP addresses. This can be useful for targeted upgrades or testing.

```bash
$ kamal upgrade -h 127.0.0.1[,127.0.0.2]
```

--------------------------------

### Perform In-Place Server Upgrade with Kamal

Source: https://github.com/basecamp/kamal-site/blob/main/docs/upgrading/overview.md

Upgrades the Kamal deployment on a server. This command stops and removes the Traefik proxy, sets up a kamal Docker network, starts kamal-proxy, and reboots the app container.

```bash
$ kamal upgrade [-d <DESTINATION>]
```

--------------------------------

### Secrets Configuration (.kamal/secrets)

Source: https://context7.com/basecamp/kamal-site/llms.txt

Example of configuring secrets in the .kamal/secrets file for password manager integration. Secrets are loaded via dotenv and made available during deployment, with options for direct use or extraction.

```bash
# .kamal/secrets

# Using 1Password
SECRETS=$(kamal secrets fetch --adapter 1password --account myteam --from Production/MyApp KAMAL_REGISTRY_PASSWORD DB_PASSWORD RAILS_MASTER_KEY)

KAMAL_REGISTRY_PASSWORD=$(kamal secrets extract KAMAL_REGISTRY_PASSWORD $SECRETS)
DB_PASSWORD=$(kamal secrets extract DB_PASSWORD $SECRETS)
RAILS_MASTER_KEY=$(kamal secrets extract RAILS_MASTER_KEY $SECRETS)

# Or use environment variables directly
# KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

# Or read from local files
# RAILS_MASTER_KEY=$(cat config/master.key)
```

--------------------------------

### Configure Build Cache for Multistage Builds (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

This shows how to configure Docker multistage build cache using either GitHub Actions (GHA) cache or Registry cache. You can specify cache type, image name, and additional options for registry cache.

```yaml
# Using GHA cache
builder:
  cache:
    type: gha
```

```yaml
# Using Registry cache
builder:
  cache:
    type: registry
```

```yaml
# Using Registry cache with different cache image
builder:
  cache:
    type: registry
    # default image name is <image>-build-cache
    image: application-cache-image
```

```yaml
# Using Registry cache with additional cache-to options
builder:
  cache:
    type: registry
    options: mode=max,image-manifest=true,oci-mediatypes=true
```

--------------------------------

### Using Kamal Secrets in .kamal/secrets

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/secrets.md

Example of how to use `kamal secrets fetch` and `kamal secrets extract` within a `.kamal/secrets` file for environment variable injection.

```shell
# .kamal/secrets

SECRETS=$(kamal secrets fetch ...)

REGISTRY_PASSWORD=$(kamal secrets extract REGISTRY_PASSWORD $SECRETS)
DB_PASSWORD=$(kamal secrets extract DB_PASSWORD $SECRETS)
```

--------------------------------

### Configure Readiness Delay in Kamal Configuration

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/overview.md

Defines the number of seconds to wait for a container to boot after it starts running. This applies only to containers without a proxy or healthcheck. Defaults to 7 seconds. This configuration is written in YAML.

```yaml
readiness_delay: 4
```

--------------------------------

### Configure Remote Builder for Single Architecture (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

This configuration specifies a remote builder for a single architecture (amd64). It's useful for speeding up builds on ARM64 machines by using a remote AMD64 host. Ensure Docker is running on the remote host.

```yaml
builder:
  arch: amd64
  remote: ssh://root@192.168.0.1
```

--------------------------------

### Define Build Secret in .kamal/secrets (Bash)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

This bash snippet shows how to define a build secret, such as GITHUB_TOKEN, in the `.kamal/secrets` file. This token can then be used to access private repositories during the build process.

```bash
# .kamal/secrets

GITHUB_TOKEN=$(gh config get -h github.com oauth_token)
```

--------------------------------

### Bootstrap Servers with Docker (Shell)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/ssh.md

Commands to update, upgrade, and install Docker, curl, and git on Ubuntu servers, then add the 'app' user to the docker group. This is a prerequisite for using Kamal with non-root users.

```shell
sudo apt update
sudo apt upgrade -y
sudo apt install -y docker.io curl git
sudo usermod -a -G docker app
```

--------------------------------

### Rollback Application Deployments with Kamal

Source: https://context7.com/basecamp/kamal-site/llms.txt

Reverts to a previous deployment version using `kamal rollback`. It first lists available containers and then stops the current container to start a new one with the specified older image, without requiring registry downloads.

```bash
# First, check available containers for rollback
kamal app containers -q

# Output shows running and stopped containers:
# App Host: 192.168.0.1
# CONTAINER ID   IMAGE                              STATUS
# 1d3c91ed1f51   myregistry/myapp:6ef8a6a8...     Up 19 minutes
# 539f26b28369   myregistry/myapp:e5d9d7c2...     Exited 27 minutes ago

# Rollback to previous version using the git SHA
kamal rollback e5d9d7c2b898289dfbc5f7f1334140d984eedae4

# This stops current container and starts a new one with the rollback image
```

--------------------------------

### Reference Build Secret in Kamal Configuration (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builder-examples.md

This YAML configuration demonstrates how to reference a build secret (e.g., GITHUB_TOKEN) defined in `.kamal/secrets`. The secret is then made available during the build process.

```yaml
# config/deploy.yml

builder:
  secrets:
    - GITHUB_TOKEN
```

--------------------------------

### Configure Path-Based Routing with Single Prefix (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/proxy.md

Implement path-based routing to serve different services under specific URL path prefixes. This example shows how to set a single path prefix. The prefix is stripped by default before forwarding.

```yaml
proxy:
  path_prefix: "/api"
```

--------------------------------

### Define YAML Anchor for Healthcheck - Kamal

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/anchors.md

Defines a reusable healthcheck configuration using YAML anchors. Anchors start with 'x-' and are defined at the root level. This example sets health check command, start period, retries, and interval.

```yaml
x-worker-healthcheck: &worker-healthcheck
  health-cmd: bin/worker-healthcheck
  health-start-period: 5s
  health-retries: 5
  health-interval: 5s
```

--------------------------------

### Pushing Application Image with Kamal Build

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/build.md

Demonstrates the execution of the `kamal build push` command. This process involves running pre-connect and pre-build hooks, acquiring a deploy lock, and then building and pushing the application image to a registry using Docker. The output shows detailed logs from the Docker build process.

```bash
$ kamal build push
Running the pre-connect hook...
  INFO [92ebc200] Running /usr/bin/env .kamal/hooks/pre-connect on localhost
  INFO [92ebc200] Finished in 0.004 seconds with exit status 0 (successful).
  INFO [cbbad07e] Running /usr/bin/env mkdir -p .kamal on server1
  INFO [e6ac30e7] Running /usr/bin/env mkdir -p .kamal on server3
  INFO [a1adae3a] Running /usr/bin/env mkdir -p .kamal on server2
  INFO [cbbad07e] Finished in 0.145 seconds with exit status 0 (successful).
  INFO [a1adae3a] Finished in 0.179 seconds with exit status 0 (successful).
  INFO [e6ac30e7] Finished in 0.182 seconds with exit status 0 (successful).
  INFO [c6242009] Running /usr/bin/env mkdir -p .kamal/locks on server1
  INFO [c6242009] Finished in 0.009 seconds with exit status 0 (successful).
Acquiring the deploy lock...
  INFO [427ae9bc] Running docker --version on localhost
  INFO [427ae9bc] Finished in 0.039 seconds with exit status 0 (successful).
Running the pre-build hook...
  INFO [2f120630] Running /usr/bin/env .kamal/hooks/pre-build on localhost
  INFO [2f120630] Finished in 0.004 seconds with exit status 0 (successful).
  INFO [ad386911] Running /usr/bin/env git archive --format=tar HEAD | docker build -t registry:4443/app:75bf6fa40b975cbd8aec05abf7164e0982f185ac -t registry:4443/app:latest --label service="app" --build-arg [REDACTED] --file Dockerfile - && docker push registry:4443/app:75bf6fa40b975cbd8aec05abf7164e0982f185ac && docker push registry:4443/app:latest on localhost
 DEBUG [ad386911] Command: /usr/bin/env git archive --format=tar HEAD | docker build -t registry:4443/app:75bf6fa40b975cbd8aec05abf7164e0982f185ac -t registry:4443/app:latest --label service="app" --build-arg [REDACTED] --file Dockerfile - && docker push registry:4443/app:75bf6fa40b975cbd8aec05abf7164e0982f185ac && docker push registry:4443/app:latest
 DEBUG [ad386911] 	#0 building with "default" instance using docker driver
 DEBUG [ad386911] 
 DEBUG [ad386911] 	#1 [internal] load remote build context
 DEBUG [ad386911] 	#1 CACHED
 DEBUG [ad386911] 
 DEBUG [ad386911] 	#2 copy /context /
 DEBUG [ad386911] 	#2 CACHED
 DEBUG [ad386911] 
 DEBUG [ad386911] 	#3 [internal] load metadata for registry:4443/nginx:1-alpine-slim
 DEBUG [ad386911] 	#3 DONE 0.0s
 DEBUG [ad386911] 
 DEBUG [ad386911] 	#4 [1/5] FROM registry:4443/nginx:1-alpine-slim@sha256:558cdef0693faaa02c0b81c21b5d6f4b4fe24e3ac747581f3e6e8f5c4032db58
 DEBUG [ad386911] 	#4 DONE 0.0s
 DEBUG [ad386911] 
 DEBUG [ad386911] 	#5 [4/5] RUN mkdir -p /usr/share/nginx/html/versions && echo "version" > /usr/share/nginx/html/versions/75bf6fa40b975cbd8aec05abf7164e0982f185ac
 DEBUG [ad386911] 	#5 CACHED
 DEBUG [ad386911] 
 DEBUG [ad386911] 	#6 [2/5] COPY default.conf /etc/nginx/conf.d/default.conf
 DEBUG [ad386911] 	#6 CACHED
 DEBUG [ad386911] 
 DEBUG [ad386911] 	#7 [3/5] RUN echo 75bf6fa40b975cbd8aec05abf7164e0982f185ac > /usr/share/nginx/html/version
 DEBUG [ad386911] 	#7 CACHED
 DEBUG [ad386911] 
 DEBUG [ad386911] 	#8 [5/5] RUN mkdir -p /usr/share/nginx/html/versions && echo "hidden" > /usr/share/nginx/html/versions/.hidden
 DEBUG [ad386911] 	#8 CACHED
 DEBUG [ad386911] 
 DEBUG [ad386911] 	#9 exporting to image
 DEBUG [ad386911] 	#9 exporting layers done
 DEBUG [ad386911] 	#9 writing image sha256:ed9205d697e5f9f735e84e341a19a3d379b9b4a8dc5d04b6219bda29e6126489 done
 DEBUG [ad386911] 	#9 naming to registry:4443/app:75bf6fa40b975cbd8aec05abf7164e0982f185ac done
 DEBUG [ad386911] 	#9 naming to registry:4443/app:latest done
 DEBUG [ad386911] 	#9 DONE 0.0s

```

--------------------------------

### Validate Kamal Configuration

Source: https://github.com/basecamp/kamal-site/blob/main/docs/upgrading/overview.md

Tests the validity of your Kamal configuration file. This command is crucial for ensuring your setup is compatible with Kamal 2.

```bash
$ kamal config
```

```bash
$ kamal config -d staging
```

```bash
$ kamal config -d beta
```

--------------------------------

### Simple Role Configuration with Host Lists and Tags

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/roles.md

Illustrates a simple way to configure a role by providing a list of hosts. Tags can be appended to hosts for custom environment variables, as detailed in the environment variables section.

```yaml
  web:
    - 172.1.0.1
    - 172.1.0.2: experiment1
    - 172.1.0.2: [ experiment1, experiment2 ]

```

--------------------------------

### Configure SSHKit Max Concurrent Starts (YAML)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/sshkit.md

Adjust the maximum number of concurrent SSH connection starts. This is crucial for deployments to many servers to prevent overwhelming the network or SSH service. The default is 30.

```yaml
sshkit:
  max_concurrent_starts: 10
```

--------------------------------

### Mount Local Directories to Accessory Container (String Format) in YAML

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/accessories.md

This YAML demonstrates mounting local directories into the accessory container using a string format. Directories are created on the host before mounting. Supports read-only (`ro`) and SELinux labels (`z`/`Z`).

```yaml
    directories:
      - mysql-logs:/var/log/mysql
      - mysql-data:/var/lib/mysql:z
```

--------------------------------

### Reference Build Arguments in Dockerfile

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/builders.md

Demonstrates how to declare and use build arguments within a Dockerfile.

```dockerfile
ARG RUBY_VERSION
FROM ruby:$RUBY_VERSION-slim as base

```

--------------------------------

### Display Kamal Help and Commands

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/help.md

The `kamal help` command displays a list of all available Kamal commands and their brief descriptions. Running `kamal help [command]` provides detailed information on a specific command. It supports options for verbose or quiet logging, specifying app versions, targeting specific hosts or roles, and setting the configuration file path.

```bash
$ kamal help
  kamal accessory           # Manage accessories (db/redis/search)
  kamal app                 # Manage application
  kamal audit               # Show audit log from servers
  kamal build               # Build application image
  kamal config              # Show combined config (including secrets!)
  kamal deploy              # Deploy app to servers
  kamal details             # Show details about all containers
  kamal docs [SECTION]      # Show Kamal configuration documentation
  kamal help [COMMAND]      # Describe available commands or one specific command
  kamal init                # Create config stub in config/deploy.yml and secrets stub in .kamal
  kamal lock                # Manage the deploy lock
  kamal proxy               # Manage kamal-proxy
  kamal prune               # Prune old application images and containers
  kamal redeploy            # Deploy app to servers without bootstrapping servers, starting kamal-proxy, pruning, and registry login
  kamal registry            # Login and -out of the image registry
  kamal remove              # Remove kamal-proxy, app, accessories, and registry session from servers
  kamal rollback [VERSION]  # Rollback app to VERSION
  kamal secrets             # Helpers for extracting secrets
  kamal server              # Bootstrap servers with curl and Docker
  kamal setup               # Setup all accessories, push the env, and deploy app to servers
  kamal upgrade             # Upgrade from Kamal 1.x to 2.0
  kamal version             # Show Kamal version

Options:
  -v, [--verbose], [--no-verbose], [--skip-verbose]  # Detailed logging
  -q, [--quiet], [--no-quiet], [--skip-quiet]        # Minimal logging
      [--version=VERSION]                            # Run commands against a specific app version
  -p, [--primary], [--no-primary], [--skip-primary]  # Run commands only on primary host instead of all
  -h, [--hosts=HOSTS]                                # Run commands on these hosts instead of all (separate by comma, supports wildcards with *)
  -r, [--roles=ROLES]                                # Run commands on these roles instead of all (separate by comma, supports wildcards with *)
  -c, [--config-file=CONFIG_FILE]                    # Path to config file
                                                     # Default: config/deploy.yml
  -d, [--destination=DESTINATION]                    # Specify destination to be used for config file (staging -> deploy.staging.yml)
  -H, [--skip-hooks]                                 # Don't run hooks
                                                     # Default: false

```

--------------------------------

### Initialize Kamal Configuration Files

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/init.md

This command creates the default configuration files required for Kamal to manage application deployments. It generates a `deploy.yml` file for deployment settings, a `.kamal/secrets` file for sensitive information, and a `.kamal/hooks` directory with sample hook scripts.

```bash
$ kamal init
Created configuration file in config/deploy.yml
Created .kamal/secrets file
Created sample hooks in .kamal/hooks
```

--------------------------------

### Downgrade Kamal Deployment

Source: https://github.com/basecamp/kamal-site/blob/main/docs/upgrading/overview.md

Reverses a Kamal 2 upgrade, reverting the deployment back to Kamal 1.9.x. This command has the same options as `kamal upgrade` and reverses the upgrade process.

```bash
kamal downgrade
```

--------------------------------

### Extract Secrets with Bitwarden Adapter

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/secrets.md

Examples of extracting a specific secret from the output of `kamal secrets fetch` when using the `bitwarden` adapter. Shows different ways to specify the secret to extract.

```bash
# Extract the secret
kamal secrets extract REGISTRY_PASSWORD <SECRETS-FETCH-OUTPUT>
kamal secrets extract MyItem/REGISTRY_PASSWORD <SECRETS-FETCH-OUTPUT>
```

--------------------------------

### Kamal Utility Commands (Bash)

Source: https://context7.com/basecamp/kamal-site/llms.txt

Provides various utility commands for managing Kamal deployments. These include auditing deployments, viewing configurations, managing container details, controlling deployment locks, pruning old resources, removing applications, checking versions, and accessing documentation.

```bash
# Show deployment audit log
kamal audit

# Show combined configuration (includes secrets!)
kamal config

# Show all container details
kamal details

# Manage deploy lock
kamal lock status
kamal lock acquire
kamal lock release

# Prune old images and containers
kamal prune all
kamal prune images
kamal prune containers

# Remove everything from servers
kamal remove

# Show Kamal version
kamal version

# Upgrade from Kamal 1.x to 2.0
kamal upgrade

# View documentation
kamal docs
kamal docs proxy

```

--------------------------------

### Extract Secrets with LastPass Adapter

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/secrets.md

Examples of extracting a specific secret from the output of `kamal secrets fetch` when using the `lastpass` adapter. Shows different ways to specify the secret to extract.

```bash
# Extract the secret
kamal secrets extract REGISTRY_PASSWORD <SECRETS-FETCH-OUTPUT>
kamal secrets extract MyFolder/REGISTRY_PASSWORD <SECRETS-FETCH-OUTPUT>
```

--------------------------------

### Extract Secrets with 1Password Adapter

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/secrets.md

Examples of extracting a specific secret from the output of `kamal secrets fetch` when using the `1password` adapter. Shows different ways to specify the secret to extract.

```bash
# All three of these will extract the secret
kamal secrets extract REGISTRY_PASSWORD <SECRETS-FETCH-OUTPUT>
kamal secrets extract MyItem/REGISTRY_PASSWORD <SECRETS-FETCH-OUTPUT>
kamal secrets extract MyVault/MyItem/REGISTRY_PASSWORD <SECRETS-FETCH-OUTPUT>
```

--------------------------------

### Configure Proxy Settings for Kamal Deployments

Source: https://context7.com/basecamp/kamal-site/llms.txt

Set up kamal-proxy for SSL, health checks, request routing, and buffering. Supports domain configuration, SSL certificates, timeouts, and request logging.

```yaml
proxy:
  # Domain configuration
  host: myapp.example.com
  # Or multiple hosts:
  # hosts:
  #   - myapp.example.com
  #   - www.myapp.example.com

  # Application port (default: 80)
  app_port: 3000

  # Enable automatic SSL via Let's Encrypt
  ssl: true

  # Or use custom SSL certificates
  # ssl:
  #   certificate_pem: SSL_CERTIFICATE
  #   private_key_pem: SSL_PRIVATE_KEY

  # Response timeout in seconds (default: 30)
  response_timeout: 60

  # Health check configuration
  healthcheck:
    path: /up
    interval: 3
    timeout: 5

  # Request/response buffering
  buffering:
    requests: true
    responses: true
    max_request_body: 100_000_000  # 100MB
    memory: 2_000_000

  # Path-based routing for microservices
  # path_prefix: "/api"

  # Request logging
  logging:
    request_headers:
      - X-Request-ID
      - User-Agent

  # Proxy container run configuration
  run:
    http_port: 80
    https_port: 443
    log_max_size: "50m"
```

--------------------------------

### Mount Local Files to Accessory Container (String Format) in YAML

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/accessories.md

This YAML demonstrates mounting local files into the accessory container using a string format. It supports specifying read-only (`ro`) or SELinux labels (`z`/`Z`). ERB files are evaluated before copying.

```yaml
    files:
      - config/my.cnf.erb:/etc/mysql/my.cnf
      - config/myoptions.cnf:/etc/mysql/myoptions.cnf:ro
      - config/certs:/etc/mysql/certs:ro,Z
```

--------------------------------

### Implement Custom Deployment Hooks in Bash

Source: https://context7.com/basecamp/kamal-site/llms.txt

Create custom scripts to run at specific deployment stages using Bash. Hooks receive deployment context via environment variables and can be used for notifications or running commands.

```bash
# .kamal/hooks/pre-deploy
#!/bin/bash
# Notify team of deployment start
curl -X POST https://slack.webhook/url \
  -d "{\"text\": \"Deploying $KAMAL_SERVICE_VERSION to $KAMAL_HOSTS\"}"

# .kamal/hooks/post-deploy
#!/bin/bash
# Notify deployment completion
curl -X POST https://slack.webhook/url \
  -d "{\"text\": \"Deployed $KAMAL_SERVICE_VERSION successfully\"}"

# Run database migrations after deploy
# .kamal/hooks/post-deploy
#!/bin/bash
kamal app exec --primary 'bin/rails db:migrate'
```

--------------------------------

### Kamal Registry Logout Example

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/registry.md

Illustrates how to log out of a Docker registry using the 'kamal registry logout' command. The output shows the execution of 'docker logout' on specified servers and their successful completion.

```bash
$ kamal registry logout
  INFO [72b94e74] Running docker logout registry:4443 on server2
  INFO [d096054d] Running docker logout registry:4443 on server1
  INFO [8488da90] Running docker logout registry:4443 on server3
  INFO [72b94e74] Finished in 0.142 seconds with exit status 0 (successful).
  INFO [8488da90] Finished in 0.179 seconds with exit status 0 (successful).
  INFO [d096054d] Finished in 0.183 seconds with exit status 0 (successful).
```

--------------------------------

### Execute Kamal Deployments

Source: https://context7.com/basecamp/kamal-site/llms.txt

Performs standard zero-downtime deployments using `kamal deploy`. Supports options to skip image building/pushing, enable verbose logging, target specific hosts or roles, and use alternative configuration files or destinations.

```bash
# Standard deployment
kamal deploy

# Skip building and pushing (use existing image)
kamal deploy --skip-push

# Deploy with verbose logging
kamal deploy --verbose

# Deploy to specific hosts only
kamal deploy --hosts=192.168.0.1

# Deploy to specific roles only
kamal deploy --roles=web

# Deploy using a different config file
kamal deploy --config-file=config/deploy.production.yml

# Deploy to a specific destination (uses config/deploy.staging.yml)
kamal deploy --destination=staging
```

--------------------------------

### Target Accessory Hosts using Various Methods in YAML

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/accessories.md

This YAML demonstrates multiple ways to specify the hosts where an accessory should run, including single host, list of hosts, role, roles, tag, or tags.

```yaml
    host: mysql-db1
    hosts:
      - mysql-db1
      - mysql-db2
    role: mysql
    roles:
      - mysql
    tag: writer
    tags:
      - writer
      - reader
```

--------------------------------

### Fetch Secrets (Doppler)

Source: https://github.com/basecamp/kamal-site/blob/main/docs/commands/secrets.md

Fetches secrets using the Doppler adapter. Secrets can be fetched by specifying the project and configuration, or by prefixing secret names with the project/config path. Requires Doppler CLI installation and configuration.

```bash
# Fetch passwords
kamal secrets fetch --adapter doppler --from my-project/prd REGISTRY_PASSWORD DB_PASSWORD

# The project/config pattern is also supported in this way
kamal secrets fetch --adapter doppler my-project/prd/REGISTRY_PASSWORD my-project/prd/DB_PASSWORD
```

--------------------------------

### Multi-Environment Deployment Configuration (YAML)

Source: https://context7.com/basecamp/kamal-site/llms.txt

Defines base deployment configuration and environment-specific overrides for staging and production using Kamal's destination feature. This allows managing different server lists, environment variables, and proxy settings per deployment target.

```yaml
# config/deploy.yml (base configuration)
service: myapp
image: myregistry/myapp

registry:
  username: myuser
  password:
    - KAMAL_REGISTRY_PASSWORD

builder:
  arch: amd64

# config/deploy.staging.yml (staging overrides)
servers:
  - staging.example.com

env:
  clear:
    RAILS_ENV: staging

proxy:
  host: staging.myapp.com

# config/deploy.production.yml (production overrides)
servers:
  - prod1.example.com
  - prod2.example.com

env:
  clear:
    RAILS_ENV: production

proxy:
  host: myapp.com
  ssl: true

```

--------------------------------

### Configure Server Roles for Deployment

Source: https://context7.com/basecamp/kamal-site/llms.txt

Define different server roles like web, workers, and scheduler, specifying hosts, resources, and commands for each role.

```yaml
servers:
  # Web servers (primary role, uses proxy by default)
  web:
    hosts:
      - 192.168.0.1
      - 192.168.0.2
    options:
      memory: 2g

  # Background job workers (no proxy)
  workers:
    hosts:
      - 192.168.0.3
      - 192.168.0.4
    cmd: "bin/jobs"
    options:
      memory: 4g
      cpus: 4
    env:
      clear:
        QUEUE: "default,mailers,critical"

  # Scheduled tasks runner
  scheduler:
    hosts:
      - 192.168.0.5
    cmd: "bin/scheduler"
```

--------------------------------

### Perform Rolling In-Place Server Upgrade with Kamal

Source: https://github.com/basecamp/kamal-site/blob/main/docs/upgrading/overview.md

Executes a rolling upgrade across multiple servers to minimize application downtime. It follows the same steps as `kamal upgrade` but applies them host by host.

```bash
$ kamal upgrade --rolling [-d <DESTINATION>]
```

--------------------------------

### Kamal Accessory Management Commands

Source: https://context7.com/basecamp/kamal-site/llms.txt

Commands for managing long-running services like databases and caches, which run independently from application deployments. Supports booting, viewing details, logs, executing commands, restarting, rebooting, and removing accessories.

```bash
# Boot all accessories
kamal accessory boot all

# Boot specific accessory
kamal accessory boot mysql

# View accessory details
kamal accessory details mysql

# View accessory logs
kamal accessory logs redis --follow

# Execute command in accessory container
kamal accessory exec mysql 'mysql -u root -p'

# Restart accessory (keeps data)
kamal accessory restart mysql

# Reboot accessory (stop, remove, start fresh)
kamal accessory reboot mysql

# Remove accessory completely
kamal accessory remove mysql

# Upgrade accessories from Kamal 1.x to 2.0
kamal accessory upgrade
```

--------------------------------

### Boot Options Configuration for Kamal

Source: https://github.com/basecamp/kamal-site/blob/main/docs/configuration/overview.md

Configuration for boot options in the Kamal project. This section specifies how to define and manage the booting behavior of the application.

```yaml
boot:
  ...
```