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`:

```yaml
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:

```yaml
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.

```yaml
image: mysql:8.0
```

## Registry

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.

```yaml
registry:
  <<: *specific-registry
```

See dash docs registry for more information:

```yaml
registry:
  ...
```

## Accessory hosts

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

```yaml
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:

```yaml
cmd: "bin/mysqld"
```

## Port mappings

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

```yaml
port: "127.0.0.1:3306:3306"
```

Labels

```yaml
labels:
  app: myapp
```

## Options

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

```yaml
options:
  restart: always
  cpus: 2
```

## Environment variables

See dash docs env for more information:

```yaml
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

```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
```

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

Note: Setting `owner` requires root access:

```yaml
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

```yaml
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:

```yaml
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:

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

## Network

The network the accessory will be attached to.

Defaults to dash:

```yaml
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.

```yaml
proxy:
  ...
```

> **Note:** 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.