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:

default_server: personal

servers:
  personal:
    ssh: dockiy@example.com

A complete config can set shared defaults:

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:

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:

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:

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.

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

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.

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 and configuration.

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

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 or Deploying applications.