By default, Dokploy can pull any publicly available Docker image. To pull images from a private registry — your own Docker Hub repository, a GitHub Container Registry namespace, an AWS ECR repository, or any other Docker-compatible registry — you must first add the registry credentials to Dokploy. Once added, those credentials are securely stored and made available to the Docker daemon when building or deploying services.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Nettalco/dokploy/llms.txt
Use this file to discover all available pages before exploring further.
Why Connect a Registry
- Private images: Deploy application images that are not publicly accessible without exposing credentials in environment variables or Dockerfiles.
- CI/CD pipeline integration: Push a freshly built image from your CI system and have Dokploy deploy it immediately using the same registry credentials.
- Organisation registries: Use images stored in a shared organisational registry (e.g. a self-hosted Harbor instance) without distributing credentials to each team member.
Adding a Registry
Open Registries settings
In the Dokploy dashboard, navigate to Settings → Registries and click Add Registry.
Enter registry details
Fill in the following fields:
| Field | Description |
|---|---|
| Registry Name | A friendly label used to identify this registry in the UI (e.g. Company ECR). |
| Registry URL | The registry hostname, without a protocol prefix (e.g. registry.hub.docker.com, ghcr.io, 123456789.dkr.ecr.us-east-1.amazonaws.com). |
| Username | Your registry username or, for AWS ECR, AWS. |
| Password / Token | Your registry password, personal access token, or, for AWS ECR, the temporary token returned by aws ecr get-login-password. |
| Image Prefix | Optional namespace prefix prepended to image names when pulling from this registry (e.g. myorg). Leave blank to use images as-is. |
Test the connection
Click Test. Dokploy calls
registry.testRegistry, which runs docker login <url> --username <user> --password-stdin against the registry and returns true on success or a descriptive error on failure.Supported Registries
Dokploy works with any registry that implements the Docker Registry HTTP API v2. Common options include:| Registry | URL Format | Notes |
|---|---|---|
| Docker Hub | registry.hub.docker.com | Use your Docker Hub username and a personal access token (PAT). |
| GitHub Container Registry | ghcr.io | Username is your GitHub username; password is a PAT with read:packages scope. |
| GitLab Registry | registry.gitlab.com | Use a deploy token or personal access token. |
| AWS ECR | <account>.dkr.ecr.<region>.amazonaws.com | Username is AWS; password is the short-lived token from aws ecr get-login-password. |
| Google Artifact Registry | <region>-docker.pkg.dev | Username is oauth2accesstoken; password is the output of gcloud auth print-access-token. |
| Self-hosted (Harbor, Nexus, etc.) | Your instance hostname | Any registry implementing Docker Registry HTTP API v2 is supported. |
Testing a Registry Connection
Two test endpoints are available:Test with inline credentials — registry.testRegistry
Used when filling in the form before saving. Accepts registryUrl, username, password, and an optional serverId. Runs docker login and returns true or throws with the Docker error message.
Test a saved registry — registry.testRegistryById
Used after a registry has already been saved. Accepts a registryId (and optional serverId) and looks up the stored credentials before running docker login. Useful for verifying that credentials are still valid after a password rotation.
On a multi-server setup, pass the
serverId of the target server to both test endpoints. Dokploy will run the docker login command on the remote server via SSH, ensuring the credentials are tested against the actual Docker daemon that will pull images at deploy time.Using a Private Image in an Application
Once a registry is saved, you can reference its images when creating an application.Create or edit an application
Open a project and click New Service → Application (or edit an existing one).
Select the registry
Choose the registered registry from the Registry dropdown. Dokploy will use the stored credentials to authenticate the pull.
Enter the image name and tag
Enter the full image path relative to the registry (e.g.
myorg/myapp:latest). Dokploy combines the registry URL and image name to form the full pull reference.Managing Registries
| Action | API Endpoint |
|---|---|
| List all registries | registry.all |
| Get a single registry | registry.one |
| Update a registry | registry.update |
| Remove a registry | registry.remove |
| Test with inline credentials | registry.testRegistry |
| Test a saved registry | registry.testRegistryById |
registry permission — create, read, update, or delete — at the organisation level.
Registry credentials (passwords and tokens) are encrypted at rest. They are never returned in plain text through any API response after the initial save.