Skip to content
Service Configuration

Service Configuration

Each service lives in a top-level directory inside the controller repository. A service directory contains composia-meta.yaml and one or more Docker Compose files.

Minimal service:

composia-meta.yaml
name: my-app
nodes:
  - main

With the default behavior, Composia looks for docker-compose.yaml in the same directory.

Top-level keys

KeyTypeRequiredDescription
namestringYesUnique service name.
project_namestringNoDocker Compose project name override. Defaults to a normalized service name.
compose_files[]stringNoCompose file paths relative to the service directory.
enabledboolNoWhether the service is active. Defaults to true.
nodes[]stringYesTarget node IDs. Each must exist in controller.nodes.
infraobjectNoDeclares this service as Caddy, Rustic, or config-only infrastructure.
networkobjectNoCaddy and DNS settings.
updateobjectNoImage update settings.
data_protectobjectNoBackup and restore data definitions.
backupobjectNoScheduled backups for protected data.
migrateobjectNoMigration-enabled protected data.
auto_deployboolNoAuto-deploy this service after repository changes.

compose_files entries must be relative paths, must stay inside the service directory, and must not be duplicated. All file references in composia-meta.yaml use repository filenames. An encrypted reference therefore includes .enc; Composia removes that suffix after decryption when the agent accesses the runtime file. References inside Compose files, Caddyfiles, scripts, and other native formats use the runtime filename without .enc.

Infrastructure services

infra.caddy

Declares the repository’s Caddy infrastructure service.

infra:
  caddy:
    compose_service: caddy
    config_dir: /etc/caddy
KeyTypeDescription
compose_servicestringCompose service name. Defaults to caddy.
config_dirstringCaddy config directory. Defaults to /etc/caddy.

Only one service can be declared as Caddy infrastructure.

infra.rustic

Declares the repository’s Rustic infrastructure service.

infra:
  rustic:
    compose_service: rustic
    profile: default
    data_protect_dir: /data-protect
    init_args:
      - --set-version
      - "2"
KeyTypeDescription
compose_servicestringCompose service name. Defaults to rustic.
profilestringRustic profile name.
data_protect_dirstringContainer path mapped to the agent’s {StateDir}/data-protect.
init_args[]stringExtra args passed to rustic init. Empty entries are rejected.

Only one service can be declared as Rustic infrastructure.

infra.config

Declares a config-only infrastructure service.

infra:
  config: {}

Config-only services cannot be combined with infra.caddy or infra.rustic. Their data_protect actions can only use files.copy.

Network

network.caddy

network:
  caddy:
    enabled: true
    source: Caddyfile
KeyTypeRequiredDescription
enabledboolNoEnables Caddy management. Defaults to false.
sourcestringCond.Caddyfile path relative to the service directory. Required when enabled.

network.dns

network:
  dns:
    - hostname: app.example.com
      record_type: A
      value: 203.0.113.10
    - hostname: app.example.com
      record_type: AAAA
      value: 2001:db8::10
KeyTypeRequiredDescription
providerstringNocloudflare, alidns, dnspod, route53, or huaweicloud. It can be inferred from the configured zone.
hostnamestringYesDNS hostname.
record_typestringNoEmpty, A, AAAA, or CNAME.
valuestringNoDNS record value. Multi-node services should set this explicitly.
proxiedboolNoProvider-specific proxy toggle, currently relevant for Cloudflare.
ttluint32NoDNS TTL.
commentstringNoDNS record comment.

A service can define any number of DNS records. The same hostname may use different record types such as A and AAAA; duplicate hostname + record type entries and combining CNAME with other types are rejected.

Image updates

update:
  enabled: true
  auto_apply: false
  check_schedule: "0 */6 * * *"
  backup_before_update: true
  digest_pin: false
  backup_data:
    - name: db
      enabled: true
  discovery_sources:
    upstream:
      sources:
        - type: github
          repo: owner/repo
      combine: first_success
      include_prerelease: false
  images:
    app:
      image: ghcr.io/example/app
      current:
        env:
          file: .env
          key: APP_VERSION
      discovery: upstream
      filter:
        type: semver
        allow:
          - patch
          - minor

Image check prerequisites

Image checks are read-only: they never download or install a service bundle, pull images, or recreate containers. Before discovering updates, the agent:

  1. Fetches a task-authorized manifest of all controller-managed persistent service files, including decrypted runtime files, and verifies their contents locally using SHA-256. Bundle permission limits and the executable bit are checked; a restrictive extraction umask is allowed. Missing or modified files require deployment before checking again. Unmanaged generated files and runtime data are not hashed, but an unmanaged .env is rejected because it changes Compose interpolation.
  2. Compares docker compose config --hash with each applicable container’s com.docker.compose.config-hash. A deployment outside Composia is accepted when the project, service, and configuration match; no successful Composia task record is required. Existing replicas must match the expected configuration hash; a stopped matching container is configuration-consistent. Inactive profile services without containers are skipped.
  3. Inspects each running container’s immutable image ID, rather than the image currently cached under its tag. Missing or ambiguous repository digests and inconsistent replicas fail the check instead of guessing an update baseline.

Configuration differences fail only the check task; they do not overwrite the service’s runtime status or its update timestamp. A newer controller revision is allowed if the service’s rendered files are unchanged. Checks observe a point in time, not a continuous guarantee against external changes.

Compose 5.5.1 or newer is required for the corrected env_file hash behavior. Agent images install docker-cli-compose from a tagged Alpine edge repository without moving the remaining packages to edge. The Compose hash does not include bind-mounted file contents or every deployment setting; it is not a complete runtime convergence check. Keep generated Caddy files outside replaceable service directories, preferably at the default <state_dir>/caddy/generated.

Most recent consistency check

Consistency is an independent configuration snapshot per service and node, not a value inferred from task status. Image checks report both file and Compose outcomes before running-image observation and remote registry discovery. Backup, Restore, and Caddy sync also passively report file-only checks; their Compose outcome is unknown because no container configuration check is performed. There is no separate consistency action, timer, automatic expiry, or history ledger.

Web instances and composia service <service> (including JSON output, without requiring --containers) show separate Files and Compose outcomes:

StatusMeaning
unknownNot checked, including a stage skipped because an earlier stage failed.
consistentThe checked configuration matched.
driftedA definite file, permission, container, or configuration-hash mismatch was found.
errorThe check could not be completed, for example due to access, transport, or tool failures.
not_applicableCompose does not apply to an infra.config service.

The most recent snapshot includes its server-recorded check time, target repository revision, source task, and stage-specific reasons. It remains historical evidence until the next check replaces it, even if runtime state or repository configuration changes afterward. Running state and image digest availability are separate observations: a stopped container can have consistent configuration while image observation fails. A later registry or image-observation error does not overwrite the recorded configuration outcomes.

Local configuration for non-deployment tasks

Only Deploy and Update install service bundles. All other tasks leave the installed service directory in place:

  • Backup and Restore require all controller-managed persistent files in both the business service and its Rustic provider to match the task revision. They use those local directories and fetch task-specific runtime parameters through an authenticated RPC, keeping those parameters in memory rather than writing .composia-backup.json or .composia-restore.json. Restore still writes the explicitly selected restore data targets.
  • Caddy sync verifies all managed files for every selected service before changing generated Caddy files. A failed preflight leaves the previous generated configuration intact, including during a full rebuild. Keep the generated directory outside service directories.
  • Stop and Restart use the installed local configuration without requiring it to match the controller. Restart retains its existing Compose down/up lifecycle; it does not install newer repository configuration.
  • Rustic init, forget, and prune use the installed local Rustic configuration without installing or updating it.

Missing or divergent files cause Backup, Restore, and Caddy sync to fail before their data or generated-file operations; they do not repair or replace files implicitly. Containers need not exist for these file-only checks, so backup after Compose down remains supported. A restore target must have matching service and Rustic configuration provisioned beforehand, even when it has never run containers. This also applies to migration targets: migration no longer bootstraps missing configuration through its Restore step. Review the difference and explicitly prepare the configuration before retrying; do not deploy an empty application over data that still needs recovery.

Controller and agents must be upgraded together. Older agents cannot use bundle installation for non-deployment tasks against the new controller. No additional database migration beyond consistency schema 13 is required for this change.

update

KeyTypeDescription
enabledboolEnables update checks for this service.
auto_applyboolApply detected updates automatically.
check_schedulestringCron schedule for update checks.
backup_before_updateboolRun backups before applying updates.
backup_data[]objectProtected data items to back up before update.
digest_pinboolPin images by digest.
discovery_sourcesmap[string]objectReusable discovery sources. Named sources cannot reference another source.
imagesmap[string]objectPer-image update definitions.

update.backup_data[]

KeyTypeDescription
namestringProtected data item name.
enabledboolInclude or exclude this item.

update.images.<name>

KeyTypeRequiredDescription
imagestringYesImage repository.
auto_applyboolNoPer-image auto-apply override.
check_schedulestringNoPer-image check schedule.
backup_before_updateboolNoPer-image backup toggle.
digest_pinboolNoPer-image digest pin toggle.
currentobjectYesCurrent version source.
discoveryobject or stringYesDiscovery config or named discovery source reference.
filterobjectCond.Required unless discovery is digest.

current

Specify exactly one of:

KeyDescription
tagStatic current tag.
env.file + env.keyRead current tag from an env file. file must be relative and stay inside the service directory.
yaml.file + yaml.pathRead current tag from a YAML file. file must be relative and stay inside the service directory.

discovery

KeyTypeDescription
sources[]objectAt least one source.
combinestringEmpty, merge, or first_success.
include_prereleaseboolInclude prerelease versions.

Discovery source types:

TypeRequired keysNotes
autoNonerepo_url is optional and must be a valid URL if set. Must be the only source.
probeNoneRequires semver filter when a filter is present.
registryNoneRegistry tag discovery.
digestNoneMust be the only source. filter must be omitted.
githubreporepo is owner/repo.
gitlabprojectGitLab project ID or path.
forgejoreporepo is owner/repo.

GitHub, GitLab, and Forgejo sources accept an optional tag_prefix. Only matching release tags are used, and the prefix is removed before filtering and image lookup.

filter

TypeRequired keysNotes
semverNoneallow may contain patch, minor, major.
dateformatDate format used to parse tags.
regexpattern, orderorder must be numeric or lexicographic.
latestNoneUses the latest candidate.

Data protection

data_protect:
  data:
    - name: db
      backup:
        strategy: database.pgdumpall
        service: postgres
        user: app
      restore:
        strategy: database.pgimport
        service: postgres
        user: app
    - name: uploads
      backup:
        strategy: files.copy_after_stop
        include:
          - ./uploads
      restore:
        strategy: files.copy
        include:
          - ./uploads

data_protect.data[]

KeyTypeRequiredDescription
namestringYesUnique data item name.
backupobjectNoBackup action.
restoreobjectNoRestore action.

Data action

KeyTypeRequiredDescription
strategystringYesfiles.copy, files.copy_after_stop, database.pgdumpall, or database.pgimport.
servicestringCond.Required for database.* strategies. Compose service name.
userstringNoPostgreSQL role passed to pg_dumpall or psql. If omitted, Composia checks the resolved service environment for PGUSER, POSTGRES_USER, POSTGRESQL_USERNAME, then POSTGRESQL_USER, in that order.
include[]stringCond.Required for files.* strategies. Use ./... or paths containing / for service paths; bare names are Docker volume names.

Backups

backup:
  data:
    - name: db
      provider: rustic
      enabled: true
      schedule: "0 2 * * *"
KeyTypeRequiredDescription
namestringYesMust reference a data_protect.data[].name with a backup action.
providerstringNoBackup provider name.
enabledboolNoEnable or disable this backup entry.
schedulestringNoCron schedule.

Migration

migrate:
  data:
    - name: db
      enabled: true
KeyTypeRequiredDescription
namestringYesMust reference a data_protect.data[].name with both backup and restore actions.
enabledboolNoEnable or disable migration for this item.
Last updated on • alexma233