Docker Registry

A Docker registry stores your images centrally so Swarm nodes can pull them independently.

When to Use

Single node: Not required. Images are transferred via SSH.
Multi-node Swarm: Recommended for large clusters. Without a registry, Dockflow transfers images to each node via SSH (docker save | ssh | docker load), which works well for small clusters but becomes slower as the number of nodes or image size grows.

Configuration

Add the following to .dockflow/config.yml:

GitHub (GHCR)


registry:
  type: ghcr
  enabled: true
  url: "ghcr.io"
  namespace: "your-org"
  username: "{{ current.env.registry_username }}"
  token: "{{ current.env.registry_token }}"

CI/CD secrets required:

REGISTRY_USERNAME (GitHub actor)
REGISTRY_TOKEN (GitHub token with packages:write scope)

GitLab


registry:
  type: gitlab
  enabled: true
  url: "registry.gitlab.com"
  namespace: "your-group/your-project"
  username: "gitlab-ci-token"
  token: "{{ current.env.registry_token }}"

CI/CD secrets required:

REGISTRY_TOKEN (CI_JOB_TOKEN is automatic in GitLab CI)

Docker Hub


registry:
  type: dockerhub
  enabled: true
  url: "docker.io"
  namespace: "your-username"
  username: "{{ current.env.registry_username }}"
  password: "{{ current.env.registry_password }}"

CI/CD secrets required:

REGISTRY_USERNAME
REGISTRY_PASSWORD

Self-Hosted


registry:
  type: custom
  enabled: true
  url: "registry.example.com"
  namespace: "your-team"
  username: "{{ current.env.registry_username }}"
  password: "{{ current.env.registry_password }}"

CI/CD secrets required:

REGISTRY_USERNAME
REGISTRY_PASSWORD

Registry credentials use Nunjucks template syntax. Values from servers.yml env vars or CI secrets are available as current.env.variable_name (lowercased).

Configuration Reference

Field	Type	Description	Default
`type`	`local` \| `dockerhub` \| `ghcr` \| `gitlab` \| `custom`	Registry type (required)	—
`enabled`	`boolean`	Enable/disable registry push	`true`
`url`	`string`	Registry hostname (required for `custom` type)	—
`namespace`	`string`	Organization or username prefix for images	—
`username`	`string`	Registry username	—
`password`	`string`	Registry password (use template syntax for secrets)	—
`token`	`string`	Registry token (alternative to password)	—
`additional_tags`	`string[]`	Extra tags to push besides the version tag	—

Image Tagging

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


registry:
  type: ghcr
  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.