Docker Registry Management Pro

Centralized management of multiple Docker container registries with automatic credential syncing to all your servers.

Pro Feature

Docker Registry Management requires a Pro license. Upgrade to unlock.

Overview

Docker Registry Management replaces the manual docker login workflow with a UI-based system. Configure registries once at the team level, and credentials are automatically pushed to every server — no SSH needed.

• Multiple registries — manage any number of registries from different providers
• Automatic sync — credentials are pushed to all team servers automatically
• Connection testing — verify credentials before deploying
• ECR token refresh — AWS ECR tokens expire every 12 hours; auto-refresh handles this
• Zero deployment changes — Coolify's existing deployment flow already mounts Docker credentials

Supported Providers

Provider	Authentication
Docker Hub	Username + access token
GitHub Container Registry (GHCR)	Username + personal access token
GitLab Container Registry	Username + PAT, custom URL support
AWS ECR	AWS access key + secret (tokens auto-refreshed)
Quay.io	Username + password (robot accounts supported)
Azure Container Registry	Login server + service principal credentials
Custom	Any V2-compatible registry with basic auth

Adding a Registry

1. Navigate to Settings > Registries
2. Click + Add Registry
3. Select the registry provider
4. Enter the required credentials:
   • Docker Hub: username + access token
   • GHCR: username + personal access token
   • ECR: AWS access key + secret key + region
   • Custom: registry URL + username + password
5. Click Test Connection to verify credentials
6. Click Save

After saving, credentials are automatically synced to all servers in your team.

Server Assignment

By default, registries are synced to all team servers. You can restrict a registry to specific servers:

1. Open the registry in Settings > Registries
2. In the Servers section, select which servers should receive these credentials
3. Only selected servers will have docker login configured for this registry

How Credential Sync Works

1. You save registry credentials in the UI
2. A sync job runs docker login on each assigned server via SSH
3. Credentials are written to ~/.docker/config.json on the server
4. Coolify's deployment process automatically mounts this file into build containers
5. docker pull and docker push work transparently for private images

No changes to your deployment configuration are needed.

Connection Testing

Before deploying with a new registry, test the connection:

1. Click Test Connection on the registry detail page
2. The system verifies authentication against the registry's API
3. Green checkmark = credentials are valid
4. Red X = authentication failed (check username/password/token)

ECR Token Auto-Refresh

AWS ECR uses temporary tokens that expire every 12 hours. Corelix automatically:

1. Detects ECR registries based on their type
2. Runs a refresh job every 6 hours
3. Obtains new tokens via the AWS SDK
4. Re-syncs updated credentials to all assigned servers

You only provide your AWS access key and secret once — token management is fully automated.

Docker Swarm

For Docker Swarm clusters, docker login on the manager node is sufficient. When deploying services with --with-registry-auth, Docker distributes the authentication tokens to all worker nodes automatically.

API

# List registries
curl -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/registries

# Create a registry
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My GHCR",
    "type": "ghcr",
    "credentials": {
      "username": "myuser",
      "password": "ghp_xxxx"
    }
  }' \
  https://coolify.example.com/api/v1/registries

# Test connection
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/registries/{uuid}/test

# Sync credentials to servers
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/registries/{uuid}/sync

# Delete a registry
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/registries/{uuid}

Credential Security

Registry credentials are stored encrypted in the database and never exposed in API responses. Passwords are masked in the UI after saving.

Troubleshooting

Pulls fail with "authentication required"

1. Verify the registry credentials are valid: click Test Connection
2. Check the sync status: ensure the server shows "Synced" in the registry detail
3. Trigger a manual sync and retry the deployment

ECR token expired

If ECR pulls fail intermittently, the auto-refresh job may have missed a cycle. Trigger a manual sync:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://coolify.example.com/api/v1/registries/{uuid}/sync

Multiple registries on the same server

Docker supports multiple registries in ~/.docker/config.json. Each registry is keyed by its URL, so there are no conflicts.