Docker registries

Coolify can pull an existing image for a Docker Image application or push an image created from application source.

Registry authentication is stored by Docker for the server user Coolify uses to run Docker commands.

Pull an existing image

Create a Docker Image application and enter an image reference:

ghcr.io/example/api:1.4.0

You can also use a SHA256 digest:

ghcr.io/example/api@sha256:<digest>

A digest identifies fixed image content. A tag can resolve to different content after the registry publishes another image with the same tag.

Push an image built by Coolify

Open General > Docker Registry.

Field	Purpose
Docker Image	Registry and repository name, such as `ghcr.io/example/api`. Leaving it empty prevents Coolify from pushing the built image.
Docker Image Tag	Optional additional tag. Coolify also tags the image with the source commit for Git-based builds.

Deploy the application and confirm the registry contains the expected image and tags.

Authenticate a private registry

Open Registries in the main sidebar, or Servers > [server] > Registries. The page lists saved server logins and registries required by applications.

Select Log in and choose the target server or servers when using the global page.
Choose a provider preset: Docker Hub, GHCR, GitLab, Google Artifact Registry, Azure ACR, AWS ECR, or a custom registry.
Enter the registry, username, and password or token. Google Artifact Registry can use a service-account JSON key.
Select Log in. Coolify runs docker login for the configured server user.
Check the login before deploying. Use Update login to replace credentials or Log out to remove a login.

Coolify does not store the token in its database. Docker stores the server login in ~/.docker/config.json; those credentials are encoded, not encrypted. Authenticate every deployment and build server that needs the image.

The API provides GET /servers/{uuid}/registries, POST /servers/{uuid}/registries, POST /servers/{uuid}/registries/{registry}/check, and DELETE /servers/{uuid}/registries/{registry}. Listing registry logins requires read:sensitive.

Authenticate through SSH

You can also connect through SSH as the configured server user and authenticate:

docker login <registry-host>

For token-based authentication:

printf '%s' "$REGISTRY_TOKEN" | docker login <registry-host> --username <registry-user> --password-stdin

Docker stores the credentials for that server user. Repeat the authentication on every machine that must push or pull the private image.

Build servers require a shared registry path

A build server cannot run the completed application. Configure a registry image name and authenticate both the build server and deployment server so the first can push the image and the second can pull it.

Use a registry with Docker Swarm

Every manager and worker that can run the application must be able to resolve, reach, and authenticate with the registry.

Coolify passes registry authentication to docker stack deploy, but the image still has to be available from the registry to every Swarm node. Test an image pull from each node before relying on the deployment.

Host a registry in Coolify

Coolify includes a Docker Registry one-click service.

The current template:

runs registry:3
creates a registry username and password through Coolify service variables
generates the htpasswd file when the service starts
stores images in the persistent registry-data volume

Create the service, configure a public domain, then use the generated credentials with docker login <registry-domain> on each server that must push or pull images.

Registry storage grows as images and tags are added. Include the registry-data volume in backups, configure retention outside Coolify, and review the upstream storage-driver documentation when the registry should use an external storage backend.