Docker Registries

Centrally manage Docker registry credentials and sync them to your servers. Supports Docker Hub, GitHub Container Registry, GitLab, Amazon ECR, Quay, Azure ACR, and custom registries.

Pro Feature

Docker Registry Management requires a Pro license. Requests to these endpoints return 402 Payment Required on free instances.

List Registries

GET /api/v1/registries

Response:

{
  "data": [
    {
      "id": 1,
      "name": "Docker Hub",
      "type": "dockerhub",
      "url": "https://index.docker.io/v1/",
      "username": "myuser",
      "is_default": true,
      "server_count": 3,
      "last_synced_at": "2024-06-15T10:30:00Z",
      "created_at": "2024-03-01T10:00:00Z"
    }
  ]
}

note

Credentials are masked in API responses. Passwords and tokens are never returned.

Registry Types

Type	Provider
dockerhub	Docker Hub
ghcr	GitHub Container Registry
gitlab	GitLab Container Registry
ecr	Amazon Elastic Container Registry
quay	Red Hat Quay
acr	Azure Container Registry
custom	Any Docker V2-compatible registry

Get Registry

GET /api/v1/registries/{id}

Returns registry details including assigned servers and sync status.

Add Registry

POST /api/v1/registries

{
  "name": "Docker Hub",
  "type": "dockerhub",
  "url": "https://index.docker.io/v1/",
  "credentials": {
    "username": "myuser",
    "password": "my-access-token"
  },
  "is_default": false
}

Parameter	Type	Required	Description
name	string	Yes	Display name
type	string	Yes	Registry type (see table above)
url	string	Yes	Registry URL
credentials	object	Yes	Authentication credentials
is_default	boolean	No	Set as default registry (default: false)

Credentials by Type

Docker Hub / GHCR / GitLab / Quay / Custom:

{
  "username": "myuser",
  "password": "access-token-or-password"
}

Amazon ECR:

{
  "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "aws_region": "eu-central-1"
}

ECR tokens are automatically refreshed every 6 hours (they expire after 12 hours).

Azure ACR:

{
  "username": "service-principal-id",
  "password": "service-principal-secret"
}

Response: 201 Created

{
  "message": "Registry added.",
  "data": {
    "id": 1,
    "name": "Docker Hub",
    "type": "dockerhub"
  }
}

Update Registry

PATCH /api/v1/registries/{id}

{
  "name": "Updated Name",
  "credentials": {
    "username": "newuser",
    "password": "new-token"
  }
}

Delete Registry

DELETE /api/v1/registries/{id}

Response:

{
  "message": "Registry deleted."
}

warning

Deleting a registry removes its credentials from all assigned servers. Running containers using images from this registry will continue to work, but new pulls may fail.

Test Connection

Verify registry credentials by attempting authentication:

POST /api/v1/registries/{id}/test

Response (success):

{
  "message": "Connection successful.",
  "authenticated": true
}

Response (failure):

{
  "message": "Authentication failed.",
  "authenticated": false,
  "error": "Invalid credentials"
}

Sync to Servers

Push registry credentials to assigned servers via docker login:

POST /api/v1/registries/{id}/sync

Response:

{
  "message": "Sync job dispatched for 3 servers."
}

The sync runs asynchronously. Credentials are written to each server's ~/.docker/config.json via SSH using docker login --password-stdin (credentials are never passed as command arguments).

Assign Servers

Specify which servers should receive the registry credentials by updating the registry:

PATCH /api/v1/registries/{id}

{
  "server_ids": [1, 2, 3]
}

After updating server assignments, trigger a sync to push credentials to the newly assigned servers.