Container Registries

Dockhand supports multiple container registries for pulling and searching images. Connect to Docker Hub, GitHub Container Registry (GHCR), private registries, or any Docker Registry V2 compatible service.

Supported Registries

Docker Hub

Public and private images from the official Docker registry

GitHub Container Registry

Container images stored in GitHub packages

Private Registries

Self-hosted or third-party Docker Registry V2 compatible

Cloud Registries

AWS ECR, Google GCR, Azure ACR, and more

Configuration

Docker Hub

Docker Hub is available by default without configuration. For private images, add authentication:

Navigate to registries

Go to Settings > Registries > Add Registry

Enter credentials

Name: Docker Hub
URL: https://registry-1.docker.io
Username: your-username
Password: your-password-or-token

Use a Docker Hub access token instead of your password for better security.

Test connection

Click Test Connection to verify credentials work correctly.

GitHub Container Registry

Connect to GHCR for images stored in GitHub packages:

Registry Configuration

Name: GitHub Container Registry
URL: https://ghcr.io
Username: your-github-username
Password: ghp_xxxxxxxxxxxx

Use a GitHub Personal Access Token (classic) with read:packages scope, not your GitHub password.

Generating GitHub Token

Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
Click Generate new token (classic)
Select scope: read:packages (and write:packages if pushing images)
Copy the token (shown only once)

Private Registry

Connect to any Docker Registry V2 compatible private registry:

Name: Company Registry
URL: https://registry.company.com
Username: service-account
Password: secret-token

Common Registry URLs

Harbor
GitLab Registry
JFrog Artifactory
Nexus Repository

https://harbor.example.com

Harbor projects require the project name in image references:

harbor.example.com/project-name/image:tag

https://registry.gitlab.com

Use GitLab username and a Personal Access Token with read_registry scope.

https://artifactory.example.com

Use Artifactory username and either password or API key.

https://nexus.example.com:8082

Configure Docker (hosted) repository and use Nexus credentials.

Cloud Registries

AWS ECR

AWS Elastic Container Registry requires temporary credentials:

# Get login credentials (valid for 12 hours)
aws ecr get-login-password --region us-east-1

Then configure in Dockhand:

Name: AWS ECR
URL: https://123456789.dkr.ecr.us-east-1.amazonaws.com
Username: AWS
Password: <output from get-login-password>

ECR credentials expire after 12 hours. For production use, automate credential refresh or use ECR credential helper.

Google Container Registry

Configure GCR using a service account:

Name: Google GCR
URL: https://gcr.io
Username: _json_key
Password: <contents of service-account.json>

The password should be the entire JSON key file content.

Azure Container Registry

Enable admin user in ACR, then configure:

Name: Azure ACR
URL: https://myregistry.azurecr.io
Username: myregistry
Password: <admin-password>

Or use service principal for better security.

Registry Schema

The registry configuration uses the following database schema:

interface Registry {
  id: number;
  name: string;           // Display name
  url: string;            // Registry URL (e.g., https://ghcr.io)
  username?: string;      // Optional username for authentication
  password?: string;      // Optional password/token for authentication
  isDefault: boolean;     // Mark as default registry for pulls
  createdAt: string;
  updatedAt: string;
}

Using Registries

Searching Images

Open image browser

Navigate to Images > Browse Registry

Select registry

Choose a registry from the dropdown or search all registries

Enter search term and browse results

View details

Click an image to see available tags and pull it

Pulling Images

When pulling an image, Dockhand automatically uses registry credentials:

# These are handled automatically with configured registries
docker pull ghcr.io/user/image:latest
docker pull registry.company.com/project/image:v1.0

Image Name Format

Different registries use different naming conventions:

Docker Hub
GHCR
Private Registry

# Official images
nginx:latest
postgres:15-alpine

# User images
username/image:tag

# Full format
docker.io/library/nginx:latest
docker.io/username/image:tag

ghcr.io/owner/image:tag
ghcr.io/organization/repository:version

registry.example.com/image:tag
registry.example.com/project/image:tag

Registry API

Dockhand uses the Docker Registry HTTP API V2:

Catalog Endpoint

List all repositories:

GET /v2/_catalog

Response:

{
  "repositories": [
    "namespace/image1",
    "namespace/image2"
  ]
}

Tags Endpoint

List tags for an image:

GET /v2/{name}/tags/list

Response:

{
  "name": "namespace/image",
  "tags": ["latest", "v1.0", "v2.0"]
}

Search Endpoint

Docker Hub search:

GET https://hub.docker.com/v2/search/repositories/?query=nginx

Private registries don’t have a search API. Dockhand searches by filtering the catalog list.

Authentication Methods

Dockhand supports multiple authentication methods:

Basic Authentication

Most common method using username and password/token:

Authorization: Basic base64(username:password)

Bearer Token

For registries using OAuth2/token authentication:

Request token from auth service
Use token in subsequent requests

Authorization: Bearer <token>

No Authentication

For public registries without authentication, leave credentials empty.

Troubleshooting

Authentication failed

Verify username and password are correct
For tokens, ensure they haven’t expired
Check token has required permissions (read:packages, etc.)
Try generating a new token
Test credentials with Docker CLI:
```
docker login registry.example.com
```

Registry not found

Verify registry URL is correct (including https://)
Check DNS resolution: nslookup registry.example.com
Test connectivity: curl https://registry.example.com/v2/
Ensure firewall allows outbound HTTPS connections

Catalog listing fails

Some registries disable catalog listing for security
Use direct image search instead of browsing
For Docker Hub, catalog listing is not supported
Check registry permissions allow catalog access

SSL certificate errors

For self-signed certificates, add CA to system trust store
Verify certificate is valid and not expired
Check certificate matches registry hostname
For testing only, Docker daemon can skip verification:
/etc/docker/daemon.json
```
{
  "insecure-registries": ["registry.example.com:5000"]
}
```

Security Best Practices

Registry credentials are stored encrypted in the database. Never share registry passwords in plain text.

Use tokens instead of passwords when available (GitHub, Docker Hub, GitLab)
Rotate credentials regularly (every 90 days)
Use read-only tokens when Dockhand doesn’t need push access
Enable HTTPS for all private registries
Audit registry access regularly to detect unauthorized usage
Use separate credentials for different environments (dev/staging/prod)

Advanced Configuration

Organization Filtering

For registries with many repositories, filter by organization:

Name: GitHub Org
URL: https://ghcr.io/myorg
Username: username
Password: token

This limits searches and catalog browsing to the myorg namespace.

Multiple Registry Instances

Configure multiple entries for the same registry with different credentials:

# Production access
Name: Company Registry (Prod)
URL: https://registry.company.com
Username: prod-readonly
Password: token1

# Development access
Name: Company Registry (Dev)
URL: https://registry.company.com
Username: dev-user
Password: token2

Default Registry

Set one registry as default for image operations:

Edit registry settings
Enable Set as default
Images without registry prefix will use this registry

Performance Considerations

Catalog caching: Large registries cache catalog for 5 minutes
Search limits: Registry searches return max 100 results
Pagination: Catalog browsing uses pagination (100 items per page)
Direct lookup: Searching with full image name (org/image) is faster than partial searches

Overview

Getting Started

Core Features

Advanced Features

Authentication & Security

Deployment

Integrations

​Supported Registries

Docker Hub

GitHub Container Registry

Private Registries

Cloud Registries

​Configuration

​Docker Hub

​GitHub Container Registry

​Generating GitHub Token

​Private Registry

​Common Registry URLs

​Cloud Registries

​Registry Schema

​Using Registries

​Searching Images

​Pulling Images

​Image Name Format

​Registry API

​Catalog Endpoint

​Tags Endpoint

​Search Endpoint

​Authentication Methods

​Basic Authentication

​Bearer Token

​No Authentication

​Troubleshooting

​Security Best Practices

​Advanced Configuration

​Organization Filtering

​Multiple Registry Instances

​Default Registry

​Performance Considerations

​Next Steps

Image Management

Container Deployment

Build docs developers (and LLMs) love

Supported Registries

Configuration

Docker Hub

GitHub Container Registry

Generating GitHub Token

Private Registry

Common Registry URLs

Cloud Registries

Registry Schema

Using Registries

Searching Images

Pulling Images

Image Name Format

Registry API

Catalog Endpoint

Tags Endpoint

Search Endpoint

Authentication Methods

Basic Authentication

Bearer Token

No Authentication

Troubleshooting

Security Best Practices

Advanced Configuration

Organization Filtering

Multiple Registry Instances

Default Registry

Performance Considerations

Next Steps