kamal - the missing manual

kamal.md

kamal

This documentation adds important additions to the docs for kamal deploy tool (see github.com/basecamp/kamal)

Destination flag

You can use kamal deploy --destination staging

This will read config/deploy.yml and config/deploy.staging.yml files, and also will read .env.staging file if it exists.

ENV vars

Both .env and .env.#destination are loaded into process env vars. So you can naturally use just process env and tools like chamber to load secrets.

So you can use them in deploy.yml this way:

servers:
  web:
    hosts: 
      - <%= ENV["APPHOST"] %>

YAML anchors

You can reference other parts of structure using &anchor and *ancho to keep to D.R.Y. principle, for example:

servers:
  web:
    hosts: 
      - &host 10.1.1.1
accessories:
  redis:
    image: redis:latest
    host: *host

Using vars in config/deploy.yml

kamal uses ERB

So you can use all of these in deploy.yml:

<% Ruby code -- inline with output %>
<%= Ruby expression -- replace with result %>

Mounting files in accessories

You can provide locally located file to be mounted as volume for the accessories. Files are uploaded and put into the home folder for SSH user.

For example:

service: test
accessories:
  registry:
    image: registry:2
    host: 10.1.1.1
    port: 5000
    files:
      # Will be placed to ${USER}/test-registry folder
      # and mounted inside the container at the specified path
      - ./config/htpasswd:/etc/docker/registry/htpasswd
    env:
      clear:
        REGISTRY_HTTP_ADDR: 0.0.0.0:5000
        REGISTRY_AUTH: htpasswd
        REGISTRY_HTTP_SECRET: asecretforlocaldevelopment
        REGISTRY_AUTH_HTPASSWD_PATH: /etc/docker/registry/htpasswd
        REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm

When you do kamal accessory boot registry

It will upload the local file config/htpasswd to the host, and then launch docker with the --volume ${LOCALPATH}:/etc/docker/registry/htpasswd argument.

Notes

• File will never be updated, to update it you need to remove the accessory (sic!) and then boot it again manually.
• If local file ends with .erb it will be read as ERB template, with env.clear: vars available.

Mounting directories in accessories

service: test
accessories:
  registry:
    image: registry:2
    host: 10.1.1.1
    port: 5000
    directories:
      # Will be copied to ${USER}/test-registry folder
      # and mounted inside the container at the specified path
      - ./config:/etc/docker/registry/

The same syntax allows to mount local directories inside accessories, by copying local files to the remote host first, then constructing a volume argument to the docker command.

Please note, that files in that directory are removed automatically when you remove accessory and copied from local host only when you boot accessory.