Configuration

Accessories

Databases, caches, and other services managed alongside the app.

Accessories can be booted on a single host, a list of hosts, or on specific roles. The hosts do not need to be defined in the Kamal servers configuration.

Accessories are managed separately from the main service — they are not updated when you deploy, and they do not have zero-downtime deployments.

Run dash accessory boot <accessory> to boot an accessory. See dash accessory --help for more information.

Configuring accessories#

First, define the accessory in the accessories:

accessories:
  mysql:

Service name#

This is used in the service label and defaults to <service>-<accessory>, where <service> is the main service name from the root configuration:

service: mysql

Image#

The Docker image to use. Prefix it with its server when using root level registry different from Docker Hub. Define registry directly or via anchors when it differs from root level registry.

image: mysql:8.0

By default accessories use Docker Hub registry. You can specify different registry per accessory with this option. Don't prefix image with this registry server. Use anchors if you need to set the same specific registry for several accessories.

registry:
  <<: *specific-registry

See dash docs registry for more information:

registry:
  ...

Accessory hosts#

Specify one of host, hosts, role, roles, tag or tags:

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

Custom command#

You can set a custom command to run in the container if you do not want to use the default:

cmd: "bin/mysqld"

Port mappings#

See https://docs.docker.com/network/, and especially note the warning about the security implications of exposing ports publicly.

port: "127.0.0.1:3306:3306"

Labels

labels:
  app: myapp

Options#

These are passed to the Docker run command in the form --<name> <value>:

options:
  restart: always
  cpus: 2

Environment variables#

See dash docs env for more information:

env:
  ...

Copying files#

You can specify files to mount into the container.

They will be uploaded from the local repo to the host and then mounted. ERB files will be evaluated before being copied.

You can use the string format: local:remote or local:remote:options where the options can be ro for read-only or z/Z for SELinux labels

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

Or you can use the hash format for custom mode and ownership.

Note: Setting owner requires root access:

files:
  - local: config/secret.key
    remote: /etc/mysql/secret.key
    mode: "0600"
    owner: "mysql:mysql"
  - local: config/ca-cert.pem
    remote: /etc/mysql/certs/ca-cert.pem
    mode: "0644"
    owner: "1000:1000"
    options: "Z"

Directories#

You can specify directories to mount into the container. They will be created on the host before being mounted.

You can use the string format: local:remote or local:remote:options where the options can be ro for read-only or z/Z for SELinux labels

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

Or you can use the hash format for custom mode and ownership.

Note: Setting owner requires root access:

directories:
  - local: mysql-data
    remote: /var/lib/mysql
    mode: "0750"
    owner: "mysql:mysql"
  - local: mysql-logs
    remote: /var/log/mysql
    mode: "0755"
    options: "z"

Volumes#

Any other volumes to mount, in addition to the files and directories. They are not created or copied before mounting:

volumes:
  - /path/to/mysql-logs:/var/log/mysql

Network#

The network the accessory will be attached to.

Defaults to dash:

network: custom

Proxy#

You can run your accessory behind the Kamal proxy for hostname-based routing and automatic SSL. The block accepts the same schema as the app-level proxy: (see dash docs proxy), though root-only keys such as loadbalancer and reboot_on_deploy have no effect inside an accessory. Declaring a proxy here makes the accessory's hosts proxy hosts: dash proxy boot (and dash deploy) will run dash-proxy on them automatically.

Accessories are never load balanced. The loadbalancer fans the app's own service out to its role targets, so an accessory always registers its hostname and TLS with the dash-proxy on its own host — whether or not the loadbalancer is active for the app. Point the accessory's DNS record at the accessory host, not at the loadbalancer.

One caveat: accessory restarts are stop-then-start (no old/new container overlap), so expect a brief interruption when restarting or rebooting.

For example:

proxy: host: mysql-admin.example.com # Route this hostname to the accessory ssl: true # Terminate SSL with a Let's Encrypt cert app_port: 8080 # Container port the accessory listens on (default: 80) healthcheck: path: /health # Health check endpoint (default: /up)

The ... below is a placeholder: accessory proxy configuration accepts the full proxy schema and is validated against it when the accessory is loaded.

proxy:
  ...

Generated from the gem's lib/dash/configuration/docs/accessory.yml — the same reference dash docs accessory prints in your terminal, so this page always matches your installed version.