Docker Registry

A Docker registry stores your images centrally. This is optional for single-node deployments but required for multi-node Swarm clusters.

When to Use

• Single node: Not required. Images are transferred via SSH.
• Multi-node Swarm: Required. Worker nodes pull images from the registry.

Configuration

Add the following to .deployment/config.yml:

registry:
  enabled: true
  url: "ghcr.io"
  namespace: "your-org"
  auth_method: "token"
  username: "{{ github_actor }}"
  token: "{{ github_token }}"

registry:
  enabled: true
  url: "registry.gitlab.com"
  namespace: "your-group/your-project"
  auth_method: "token"
  username: "gitlab-ci-token"
  token: "{{ ci_job_token }}"

registry:
  enabled: true
  url: "docker.io"
  namespace: "your-username"
  auth_method: "basic"
  username: "{{ docker_username }}"
  password: "{{ docker_password }}"

registry:
  enabled: true
  url: "registry.example.com"
  namespace: "your-team"
  auth_method: "basic"
  username: "{{ registry_username }}"
  password: "{{ registry_password }}"

Configuration Reference

Image Tagging

By default, images are tagged with the deployment version. You can add extra tags that point to the same image:

registry:
  enabled: true
  url: "ghcr.io"
  namespace: "your-org"
  additional_tags:
    - "latest"
    - "{env}"

Example: Deploying version 1.2.0 to production produces:

ghcr.io/your-org/my-app:1.2.0       # main tag (version)
ghcr.io/your-org/my-app:latest      # additional tag
ghcr.io/your-org/my-app:production  # additional tag ({env} replaced)

Available variables: {version}, {env}, {branch}, {sha}

Troubleshooting

Authentication failed: Test credentials manually with docker login.

Push denied: Verify write access to the namespace.

Workers cannot pull: Ensure all Swarm nodes can reach the registry. For private registries, authenticate on each node.