---
url: /config.md
description: Configure DockIY for your server and applications.
---

# Configuration reference

DockIY uses configuration files at different levels:

| File | Location | Purpose |
| --- | --- | --- |
| Global config | User config directory; see below | Server profiles and shared defaults |
| `dockiy.config.yml` | Current working directory | Local overrides for the global config |
| `dockiy.yml` | Application repository root | Application environments, images, and hooks |
| `.dockiy.template.yml` | Template repository root | Optional app-init cleanup and SOPS setup |
| `dockiy.manifest.yml` | Infrastructure repository root | Server Compose file and files to synchronize |
| `.sops.yaml` | Repository containing encrypted files | SOPS encryption rules |
| `.enc.env` | Infrastructure or application repository | Tracked, encrypted environment values |

## Priority

### Choosing the global config file

DockIY chooses one global config file in this order:

1. The global `--config <path>` option
2. The `DOCKIFY_CONFIG` environment variable
3. The operating system's default user config directory

`--config` and `DOCKIFY_CONFIG` select the global config file; they do not
merge multiple global config files.

### Resolving server values

For each server value, the effective priority from lowest to highest is:

1. Built-in defaults
2. The global `defaults` block
3. The local `defaults` block
4. The selected global `servers.<name>` profile
5. The matching local `servers.<name>` value

The local file can also override `default_server` and add server profiles.
Overrides are merged by key, including nested `registry` values.

The environment argument and command options choose an operation, but do not
change the server configuration priority.

## Global config

### Location

The default path is:

| Operating system | Default location |
| --- | --- |
| Linux | `${XDG_CONFIG_HOME}/dockiy/config.yml`, or `~/.config/dockiy/config.yml` when `XDG_CONFIG_HOME` is unset |
| macOS | `~/Library/Application Support/dockiy/config.yml` |
| Windows | `%AppData%/dockiy/config.yml` |

Use `dockiy config validate` to see the selected path. Set
`DOCKIFY_CONFIG` or pass `--config <path>` to use another path.

### Format

A minimal global config is:

```yaml
default_server: personal

servers:
  personal:
    ssh: dockiy@example.com
```

A complete config can set shared defaults:

```yaml
default_server: personal

defaults:
  compose_project_name: dockiy
  remote_path: ~/dockiy
  platform: linux/amd64
  registry:
    tunnel_port: 5500
    remote_port: 5000

servers:
  personal:
    ssh: dockiy@example.com
```

### Top-level fields

| Field | Required | Description |
| --- | --- | --- |
| `default_server` | Yes | Profile used when a command does not select another profile |
| `defaults` | No | Values shared by all server profiles |
| `servers` | Yes | Named server profiles; at least one is required |

`default_server` must match a key under `servers`.

### Server fields

These fields are valid in `defaults` and in each `servers.<name>` profile:

| Field | Description |
| --- | --- |
| `compose_project_name` | Infrastructure Compose project; default `dockiy` |
| `ssh` | SSH alias or `user@address`; required in the selected profile |
| `remote_path` | DockIY root on the server; default `~/dockiy` |
| `platform` | Docker build platform; default `linux/amd64` |
| `registry.tunnel_port` | Local registry tunnel port; default `5500` |
| `registry.remote_port` | Server registry port; default `5000` |

`ssh` is a profile-only setting. Other profile values override the same
values from `defaults`. A `remote_path` beginning with `~/` is relative to
the remote SSH user's home directory.

### Multiple servers

Add one named profile for each server, then choose the profile used by default:

```yaml
default_server: personal

servers:
  personal:
    ssh: dockiy@example.com
  experiments:
    ssh: dockiy@my-experiments.com
    remote_path: ~/dockiy-experiments
```

The profile name is just a local identifier. The `ssh`, remote path, registry
ports, and other server settings belong to the profile. Use
`dockiy config validate` after editing the file.

## Local override

### `dockiy.config.yml`

Create this optional file in the current working directory:

```yaml
default_server: experiments

servers:
  experiments:
    ssh: some-ssh-connection-string
```

The file can contain any of the global config fields, but it may be partial.
It is not searched for in parent directories. To make one application use a
different server from the global default, put this file at that application's
repository root and run DockIY there:

```yaml
default_server: experiments
```

The selected profile must exist in the global config, unless the local file
also defines it. The local file affects commands run from that directory,
including application deploy and status commands. It contains no SSH
credentials by itself, but keep it ignored by Git when the choice is personal
or machine-specific.

The override is used by `config validate`, server commands, application
commands that connect to a server, and `releases clean`. Keep it ignored by
Git when it contains machine-specific values.

## Application config

### `dockiy.yml`

This file belongs at the application repository root. Application commands find
the repository root from the current directory.

```yaml
name: my-app

environments:
  default:
    host: example.com
    compose_file: docker-compose.yml

hooks:
  build: scripts/build.sh
  start: scripts/start.sh
  healthcheck: scripts/healthcheck.sh
```

### Fields

| Field | Description |
| --- | --- |
| `name` | Application identifier |
| `images` | Image names produced by `hooks.build`; defaults to `app` |
| `environments` | `default`, or both `staging` and `production` |
| `environments.<name>.host` | Public hostname |
| `environments.<name>.compose_file` | Compose file for the environment |
| `environments.<name>.secrets_file` | Optional tracked SOPS-encrypted file |
| `hooks.build` | Required local build hook |
| `hooks.start` | Required remote start hook |
| `hooks.pre_start` | Optional pre-start hook |
| `hooks.rollback_pre_start` | Optional rollback pre-start hook |
| `hooks.healthcheck` | Optional healthcheck hook |

Only `default`, or `staging` and `production`, are valid environment
combinations. All referenced paths must be clean relative paths.

DockIY provides these values to Compose files and hooks:

| Variable | Value |
| --- | --- |
| `DOCKIY_APP_HOST` | Selected environment hostname |
| `DOCKIY_COMPOSE_PROJECT_NAME` | Application Compose project |
| `DOCKIY_ENVIRONMENT` | Selected environment |
| `DOCKIY_GIT_COMMIT` | Deployed Git commit |
| `DOCKIY_PLATFORM` | Configured build platform |
| `DOCKIY_RELEASE` | Release Git tag |
| `DOCKIY_<NAME>_IMAGE` | Registry reference for each configured image |

See [Deploying applications](/guide/deploying-apps) for deployment commands.

## Server config

### `dockiy.manifest.yml`

This file belongs at the root of the local infrastructure repository. By
default, `server init` creates or uses `./dockiy/dockiy.manifest.yml`
relative to the directory where it runs. If you run the command from the
infrastructure repository itself, that repository is used directly.

```yaml
server:
  compose_file: docker-compose.yml
  files:
    - docker-compose.yml
    - dozzle_data/users.yml
```

| Field | Description |
| --- | --- |
| `server.compose_file` | Infrastructure Compose file |
| `server.files` | Exact relative paths synchronized to the server |

`server.files` must include `server.compose_file`. The runtime `.env` is
managed separately and must not be listed here.

## Template config

### `.dockiy.template.yml`

This optional file belongs at the root of a template repository. `app init`
reads it after cloning, applies its settings, and removes the file from the
generated application.

```yaml
remove:
  - .enc.local.env
  - .enc.staging.env
  - .enc.production.env
sops:
  config_file: .sops.yaml
  path_regex: '^\.enc\.(local|staging|production)\.env$'
```

| Field | Description |
| --- | --- |
| `remove` | Exact repository-relative files to remove; missing files are ignored |
| `sops.config_file` | Template SOPS config to remove and replace; default `.sops.yaml` |
| `sops.path_regex` | Optional path regex for the generated SOPS config |

The `sops` section is optional. When present, `app init` can create a new SOPS
config using the user's age/SSH recipients, or copy rules from `--sops-config`
unchanged. Remove paths must refer to files inside the generated project;
directories are not supported.

## SOPS files

### `.sops.yaml`

SOPS reads this file from the repository containing the encrypted file. It
defines encryption rules for matching paths using any backend supported by
SOPS. See [SOPS identities](https://getsops.io/docs/usage/identities/) and
[configuration](https://getsops.io/docs/usage/config-file/).

### `.enc.env`

This is the encrypted source file for environment values.

* In the infrastructure repository, it stores the shared server environment.
* In an application repository, set `environments.<name>.secrets_file` to it.
* Keep it tracked in Git.
* Never replace it with a tracked plaintext `.env`.

For the infrastructure repository, DockIY decrypts `.enc.env` locally and
uploads a temporary runtime `.env` to the server. A local plaintext `.env`
is unsupported.

## Validate configuration

Validate the selected global config and local override:

```bash
dockiy config validate
```

Application manifests are validated when an application command runs. Server
manifests are validated by `server init`, `server update`, and
`server doctor`.

Continue with the [CLI reference](/cli/) or [Deploying applications](/guide/deploying-apps).