# Docker Registries

Source: https://next.coolify.io/docs/applications/builds/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](https://next.coolify.io/docs/applications/deployments/docker-image) and enter an image reference:

```sh
ghcr.io/example/api:1.4.0
```

You can also use a SHA256 digest:

```sh
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.

<span id="docker-credentials" />

## 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.

1. Select **Log in** and choose the target server or servers when using the global page.
2. Choose a provider preset: Docker Hub, GHCR, GitLab, Google Artifact Registry, Azure ACR, AWS ECR, or a custom registry.
3. Enter the registry, username, and password or token. Google Artifact Registry can use a service-account JSON key.
4. Select **Log in**. Coolify runs `docker login` for the configured server user.
5. 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:

```bash
docker login <registry-host>
```

For token-based authentication:

```bash
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.

> **Warning: 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](https://next.coolify.io/docs/services/docker-registry).

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](https://distribution.github.io/distribution/storage-drivers/) when the registry should use an external storage backend.