gem install kamal

または bundle で導入

bundle add kamal --group development

Dockerコンテナとして実行すれば、Rubyのインストールは不要です。

bundle exec kamal deploy -d staging
bundle exec kamal app exec -i --reuse bash -d production
bundle exec kamal accessory boot all -d production
bundle exec kamal proxy details -d production

指定したローカルファイルをリモートサーバー上にアップロードしてマウントします。

  db:
    image: mysql:8.0
    # 省略
    files:
      # - ローカルファイル名:コンテナ内でのマウントパス
      - config/mysql/production.cnf:/etc/mysql/my.cnf
      - db/production.sql:/docker-entrypoint-initdb.d/setup.sql

files に指定したローカルファイルは、 kamal accessory boot コマンドでアップロードされます。（該当するコード）

[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_general_ci
max_allowed_packet=32MB
authentication_policy=mysql_native_password

[client]
default-character-set=utf8mb4

CREATE DATABASE IF NOT EXISTS `myapp_production` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

アクセサリコンテナ起動前にリモートサーバー上に指定したディレクトリを作成して、Dockerコンテナにマウントします。 相対パスで記載した場合はアクセサリ用のデータディレクトリの下に作成します。絶対パスで指定した場合はそのパスに作成します。いずれもSSHで接続するデプロイユーザーの権限で作成できる必要があります。

accessories:
  db:
    image: mysql:8.0
    # 省略
    directories:
      - "/data/mysql:/var/lib/mysql"
      - "logs:/var/log/mysql"

$ bundle exec kamal accessory boot db
# 省略
# リモートサーバー上に以下のディレクトリが作成される。
#   /data/mysql
#   デプロイユーザーのホームディレクトリ/サービス名-アクセサリ名/logs
  INFO [4f1ab1b1] Running /usr/bin/env mkdir -p $PWD/myapp-db/logs on myapp.host
  INFO [4f1ab1b1] Finished in 0.021 seconds with exit status 0 (successful).
  INFO [0105230b] Running /usr/bin/env mkdir -p /data/mysql on myapp.host
  INFO [0105230b] Finished in 0.022 seconds with exit status 0 (successful).

$ bundle exec kamal accessory remove db
This will remove all containers, images and data directories for redis. Are you sure? [y, N] (N) y
# 省略
  INFO [a6aa6962] Running /usr/bin/env rm -rf myapp-db on myapp.host
  INFO [a6aa6962] Finished in 0.020 seconds with exit status 0 (successful).

Docker の --volume オプションそのもの。 リモートサーバー上の指定したパスをDockerコンテナにマウントします。 directories と異なり事前に作成しておく必要があります。

volumes:
  - "/data/storage:/app/storage"

accessories:
  db:
    image: mysql:8.0
    # 省略
    volumes:
      - "/data/mysql:/var/lib/mysql"

コマンド実行時のコンテナ内の環境変数を書き出しておき、 BASH_ENV で反映する。

servers:
  # 省略
  cron:
    cmd:
      bash -c "eval \$(printenv | awk -F= '{print \"export \" \"\\\"\"\$1\"\\\"\"\"=\"\"\\\"\"\$2\"\\\"\" }' >> /etc/environment); cat config/crontab | crontab - && cron -f"
    hosts:
      - 123.456.789.012

SHELL=/bin/bash
BASH_ENV=/etc/environment
30 0 * * * cd /app && bundle exec rails statistic:daily > /proc/1/fd/1 2>&1

$ bundle exec kamal accessory boot db

service: myapp
# 省略
env:
  clear:
    # 省略
    # ホスト名は サービス名-アクセサリ名
    DB_HOST: myapp-db
    DB_USER: root
  secret:
    # 省略
    - DB_PASSWORD

accessories:
  db:
    image: mysql:8.0
    host: myapp.host
    env:
      clear:
        MYSQL_ROOT_HOST: '%'
      secret:
        - MYSQL_ROOT_PASSWORD
    files:
      - config/mysql/my.cnf:/etc/mysql/my.cnf
      - db/setup.sql:/docker-entrypoint-initdb.d/setup.sql
    directories:
      - "/data/mysql:/var/lib/mysql"

$ vi /etc/logrotate.d/mysqldump
$ /usr/sbin/logrotate -v -f /etc/logrotate.d/mysqldump

/backup/mysqldump/myapp_production.sql.gz {
    daily
    rotate 14
    missingok
    notifempty
    nocompress
    postrotate
        docker run \
        --rm --net=kamal -v "/root/.my.cnf:/root/.my.cnf" \
        mysql:8.0 \
        mysqldump \
        -h myapp-db \
        --flush-logs \
        --quote-names \
        --hex-blob \
        --single-transaction \
        myapp_production | gzip > /backup/mysqldump/myapp_production.sql.gz
    endscript
}

$ docker run \
-it --rm --net=kamal \
-v "/root/.my.cnf:/root/.my.cnf" \
-v "/tmp/myapp_production.sql:/tmp/myapp_production.sql" \
mysql:8.0 \
/bin/sh -c "mysql -h myapp-db myapp_production < /tmp/myapp_production.sql"

accessories:
  db:
    # 省略
    cmd: /usr/local/bin/mysqld.sh
    # 省略
    files:
      - config/mysql/mysqld.sh:/usr/local/bin/mysqld.sh
      - config/mysql/my.cnf:/etc/mysql/my.cnf
    # 省略

filesについてはこちら

[mysqld]
log_error = /var/log/mysqld.log

#!/usr/bin/env bash
set -euo pipefail

##
# This script exists to work-around the fact that
# mysql does not support logging to stdout
#
# This will tail the file logs configured in ./my.cnf
##

LOG_PATHS=(
  '/var/log/mysqld.log'
)
for LOG_PATH in "${LOG_PATHS[@]}"; do
  # https://serverfault.com/a/599209
  ( umask 0 && truncate -s0 "$LOG_PATH" )
  tail --pid $$ -n0 -F "$LOG_PATH" &
done

docker-entrypoint.sh mysqld

# 更新前を確認
$ bundle exec kamal accessory details db -d production
  INFO [a6f33b36] Running docker ps --filter label=service=myapp-db on myapp.host
  INFO [a6f33b36] Finished in 0.909 seconds with exit status 0 (successful).
Accessory db Host: myapp.host
CONTAINER ID   IMAGE              COMMAND                  CREATED              STATUS              PORTS                                 NAMES
01e9150831d2   mysql:8.0-debian   "docker-entrypoint.s…"   31 hours ago     Up 27 hours   127.0.0.1:3306->3306/tcp, 33060/tcp   myapp-db

# コンテナの作り直し
$ bundle exec kamal accessory reboot db -d production

# 更新後の確認
$ bundle exec kamal accessory details db -d production
  INFO [54852e87] Running docker ps --filter label=service=myapp-db on myapp.host
  INFO [54852e87] Finished in 0.541 seconds with exit status 0 (successful).
Accessory db Host: myapp.host
CONTAINER ID   IMAGE              COMMAND                  CREATED          STATUS          PORTS                                 NAMES
0b17edc0d04c   mysql:8.0-debian   "docker-entrypoint.s…"   21 seconds ago   Up 20 seconds   127.0.0.1:3306->3306/tcp, 33060/tcp   myapp-db

$ bundle exec kamal accessory exec db -i --reuse bash -d production
Launching interactive command via SSH from existing container...
root@0b17edc0d04c:/# 

デプロイフックに書くと、Kamal Proxyの設定をコードで管理することができます。
デプロイフック中では、bundlerでインストールしている場合も bundle exec なしで動作します。

#!/bin/bash
set -ex

# Kamal Proxy コンテナの起動オプションを設定
kamal proxy boot_config set --https-port=10080 --http-port=10443

bundle exec kamal proxy boot_config set --https-port=10080 --http-port=10443

production環境のwebロールで実行中のコンテナにインタラクティブモードで接続する
bash
ruby ➜ /src (master) $ bundle exec kamal app exec --reuse -i bash -r web -d production
Launching interactive command with version latest-production via SSH from existing container on myapp.xxx...
root@f1eeec5f4d32:/app# echo $RAILS_ENV
production
root@f1eeec5f4d32:/app#


bundle exec kamal app logs
# follow
bundle exec kamal app logs -f
# ロールを指定
bundle exec kamal app logs -f -r web
# 環境を指定
bundle exec kamal app logs -f -d production

logging:
  driver: syslog
  options:
    syslog-address: udp://127.0.0.1:514
    syslog-facility: daemon
    tag: "web"
    syslog-format: rfc5424

特定のロールのログ設定は、ロールの下に書く。

servers:
  # 省略
  job:
    cmd: bin/jobs
    logging:
      driver: syslog
      options:
        syslog-address: udp://127.0.0.1:514
        syslog-facility: daemon
        tag: "job"
        syslog-format: rfc5424

デプロイフックに書くと、Kamal Proxyの設定をコードで管理することができます。
デプロイフック中では、bundlerでインストールしている場合も bundle exec なしで動作します。
```bash:.kamal/hooks/pre-deploy

!/bin/bash

set -ex

Kamal Proxy コンテナの起動オプションを設定

- ホストの rsyslog にログを出力

- ログのフォーマットを RFC5424 にする

kamal proxy bootconfig set \
--dockeroptions \
log-driver=syslog \
log-opt=syslog-address=udp://127.0.0.1:514 \
log-opt=syslog-facility=daemon \
log-opt=tag=proxy \
log-opt=syslog-format=rfc5424 \
--log-max-size=""
```

bundle exec kamal proxy boot_config set \
  --docker_options \
    log-driver=syslog \
    log-opt=syslog-address=udp://127.0.0.1:514 \
    log-opt=syslog-facility=daemon \
    log-opt=tag=proxy \
    log-opt=syslog-format=rfc5424 \
  --log-max-size=""
bundle exec kamal proxy reboot

リモートサーバー上の ~/.kamal/proxy/options に保存され、 kamal-proxy コンテナ起動時の docker コマンドのオプションとして使用されます。

deploy@myapp:~$ cat ~/.kamal/proxy/options
--publish 80:80 --publish 443:443 --log-driver=syslog --log-opt=syslog-address=udp://127.0.0.1:514 --log-opt=syslog-facility=daemon --log-opt=tag=proxy --log-opt=syslog-format=rfc5424 

実行中のアプリバージョンの確認

$ bundle exec kamal app version -d production
App Host: myapp.host
b1680c634f06ea84670e3db6fa2669a792480d7e

デプロイ（新しいバージョン）

$ bundle exec kamal deploy -d production
$ bundle exec kamal app version -d production
App Host: myapp.host
95bd526cb24478d392b139d51031108e9c849986

アプリバージョンを指定して戻す

$ bundle exec kamal app boot --version=b1680c634f06ea84670e3db6fa2669a792480d7e -d production
$ bundle exec kamal app version -d production
App Host: myapp.host
b1680c634f06ea84670e3db6fa2669a792480d7e

$ bundle exec kamal proxy details -d production
  INFO [f6932bb7] Running docker ps --filter name=^kamal-proxy$ on myapp.host
  INFO [f6932bb7] Finished in 1.141 seconds with exit status 0 (successful).
Proxy Host: myapp.host
CONTAINER ID   IMAGE                         COMMAND             CREATED       STATUS       PORTS                                                                      NAMES
e6d2797bae5e   basecamp/kamal-proxy:v0.8.4   "kamal-proxy run"   2 weeks ago   Up 2 weeks   0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp   kamal-proxy
$ bundle exec kamal proxy reboot -d production
This will cause a brief outage on each host. Are you sure? [y, N] (N) y

ssh:
  user: deploy
  # 鍵を指定する場合
  # ssh-agentを使用する場合は不要
  # keys:
  #   - ~/.ssh/deploy.id_ed2551

リモートサーバーに自身でDockerをインストールして、デプロイ用ユーザーで操作できるようにしておきます。

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo adduser deploy
sudo usermod -aG docker deploy

# 設定（ログドライバなど他に設定がある場合はそれも同時に書く）
bundle exec kamal proxy boot_config set \
  --docker_options \
    userns=host
# 設定内容の確認
bundle exec kamal proxy boot_config get
# 再起動して反映
bundle exec kamal proxy reboot

リモートホスト上で実行

$ docker exec kamal-proxy kamal-proxy ls
Service      Host       Target             State    TLS  
myapp-web  myapp.host  bc7fd00e0df7:3000  running  yes 
$ docker exec kamal-proxy kamal-proxy remove myapp-web

ローカルホスト上で実行

$ bundle exec kamal deploy

Kamal Proxy の Dockerfileを確認すると、 kamal-proxy ユーザーで実行されていました。

kamal-proxy コンテナは /home/kamal-proxy/.config/kamal-proxy にマウントします。
userns-remap の場合、マウントしたディレクトリの書き込み権限がコンテナ内の kamal-proxy ユーザーになく、正しく動作しないことがわかりました。

$ docker inspect <kamal-proxyのコンテナID>

マウント設定を抜粋

        "Mounts": [
            {
                "Type": "volume",
                "Name": "kamal-proxy-config",
                "Source": "/var/lib/docker/1001.1001/volumes/kamal-proxy-config/_data",
                "Destination": "/home/kamal-proxy/.config/kamal-proxy",
                "Driver": "local",
                "Mode": "z",
                "RW": true,
                "Propagation": ""
            }
        ],