Free tools Windows power users keep installed
One-click scans. No signup required.
To deploy a private image in Coolify, add the image as a Docker Image application, then log in to the registry on the server user that Coolify uses for Docker commands. The registry login is separate from Git authentication. If an image is built elsewhere, authenticate both the build server (for pushing) and the Coolify deployment server (for pulling). Use a complete image reference and an internal listening port, then deploy and read the logs for any pull or startup error.
Antihost offers VPS plans with one-click Coolify, NVMe storage and a 14-day free trial.
What Coolify needs to pull a private image
A Docker image application has two independent requirements: an exact image reference and Docker credentials on the machine that will pull it. For example, ghcr.io/example/api:1.4.0 identifies the registry host, repository path, and version tag. You can also identify the image with a repository and tag entered through the UI, or with a digest such as ghcr.io/example/api@sha256:<digest>.
As an Amazon Associate I earn from qualifying purchases.
Coolify performs the pull on the deployment server. A Git deploy key does not satisfy this requirement: it can clone a private source repository, but it cannot authenticate Docker to a private container registry. Registry credentials are saved by Docker in the server user’s ~/.docker/config.json. Coolify’s documentation notes that this data is encoded, not encrypted, so access to that server account and its backups must be controlled.
Connect a private registry through the Coolify interface
1. Create a Docker Image application
- Open the relevant Coolify project and environment.
- Select + New > Docker Image.
- Enter the complete image reference, such as
ghcr.io/example/api:1.4.0. Use the repository name plus a tag, or a SHA256 digest, when that is how your registry publishes images.
Do not omit the registry hostname when the image is not hosted on Docker Hub. A wrong host or repository path can produce an authorization error even when the token itself is valid.
#1 Best Overall
2. Add the registry login for the correct server
- Open Registries in Coolify’s main sidebar, or go to Servers > [server] > Registries.
- Select Log in.
- Choose the registry type: Docker Hub, GHCR, GitLab, Google Artifact Registry, Azure ACR, AWS ECR, or Custom.
- Enter the registry host, username, and password or access token.
- Save the login for the server that will run the application.
Coolify runs docker login for the configured server user. Logging in as a different Linux account does not authenticate Coolify, because each account has its own Docker configuration file.
3. Set the container’s listening port
In the Docker Image application’s settings, set Ports Exposes to the port on which the process listens inside the container. This is the internal container port, not necessarily the public port on your domain or the host’s SSH port. Add the domain and any required runtime settings, environment variables, volumes, or health configuration used by the image.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →4. Deploy and inspect the result
- Select Deploy.
- Watch the deployment logs for the image pull, container creation, and application startup.
- If the pull succeeds but the application is unreachable, verify Ports Exposes, the process’s bind address, and the domain configuration separately from registry authentication.
Log in with SSH instead of the UI
You can configure the same Docker credentials from an SSH session, but you must connect as the same server user that Coolify uses. Log in to the registry host with:
docker login <registry-domain>Docker will prompt for the username and password or token. To avoid placing a token in shell history, pipe it through standard input:
printf '%s' "$REGISTRY_TOKEN" | docker login <registry-domain> --username "$REGISTRY_USERNAME" --password-stdinAfter a successful login, Docker writes the credential configuration for that account. Return to Coolify and redeploy the application so the deployment server retries the pull with the new credentials.
Which credentials are needed in each architecture?
Single deployment server
For an image that is already published, the deployment server needs pull permission on the repository. Authenticate that server’s Coolify user before the first deployment and again after rotating or replacing the token.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Separate build and deployment servers
A build server that creates and publishes an image needs push permission. The deployment server needs pull permission. These are two Docker logins on two machines; a successful push does not prove that the deployment server can pull.
| Machine | Operation | Required registry access | Typical failure when missing |
|---|---|---|---|
| Build server | Publishes the completed image | Push permission for the repository | Push is rejected or the image tag never appears |
| Deployment server | Pulls the image for Coolify | Pull permission for the repository | Coolify reports an unauthorized or denied pull |
When using a build-server deployment flow, select Docker Image in Coolify and authenticate both server roles. Keep the credentials on the account that actually runs Docker on each machine.
Docker Swarm
Swarm adds a node-by-node requirement. Every manager and worker that may schedule the application must be able to resolve the registry hostname, reach it over the network, and authenticate. Test a pull from each eligible node, not only from the manager where you issued the deployment command. A node that cannot pull the image can leave a service task pending or repeatedly failing.
Choose tags and digests for predictable deployments
Version tags
A version tag such as ghcr.io/example/api:1.4.0 is easy to read and works well when release tags are treated as immutable. Record the version in your deployment configuration so a later change is intentional and reviewable.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteSHA256 digests
A digest such as ghcr.io/example/api@sha256:<digest> identifies fixed image content. It is the strongest choice when you need the exact same bytes on every redeploy or when investigating whether an image changed without a configuration change.
Mutable tags
Tags such as latest can point to different content later. Coolify warns that a mutable tag may resolve to new content on a subsequent deployment or restart. If a deployment appears to change unexpectedly, replace the mutable tag temporarily with a version tag or digest and compare the results.
| Reference style | Readability | Content repeatability | Best use |
|---|---|---|---|
Mutable tag, for example latest |
High | Not guaranteed | Only when changing content on that tag is deliberate |
Version tag, for example 1.4.0 |
High | Depends on the publisher keeping the tag immutable | Normal release deployments |
| SHA256 digest | Lower at a glance | Fixed to one image content | Audited, reproducible, or incident-response deployments |
External registry or a registry hosted in Coolify?
Use an external registry when
- Your organization already publishes images to a managed registry.
- Build and deployment servers are in different networks and need a common, reachable endpoint.
- You want registry availability and storage operations handled outside the Coolify host.
Regardless of provider, each machine that pushes or pulls must have its own login, and the token must include the operation it performs.
Recommended Free Tools
Host a registry with Coolify when
Coolify offers a Docker Registry one-click service. The current template runs registry:3, creates credentials from service variables, generates an htpasswd file at startup, and stores images in a persistent registry-data volume.
- Create the Docker Registry service from Coolify’s one-click services.
- Configure a public domain for the registry endpoint.
- Set the service variables that generate the registry credentials.
- Wait for the service to start and use the generated username and password with
docker login <registry-domain>. - Log in on every server that must push or pull, including separate build servers and every eligible Swarm node.
Include registry-data in backups. Plan storage retention before publishing images, because deleting old tags or containers does not by itself define a retention policy for registry content. A lost volume can mean lost image data even when the Coolify application configuration remains.
Diagnose unauthorized and denied-pull errors
Work through these checks in order. Change one variable at a time and retry with a version tag or digest so an image update does not obscure the authentication problem.
Best Value
Check the image reference
- Compare the registry hostname character for character.
- Check the repository path, including organization or namespace segments.
- Confirm the tag exists, or verify the digest is complete.
- Make sure a private-registry hostname was not accidentally replaced with a Docker Hub-style short name.
Check token permissions
- For a deployment-only server, the token must be allowed to pull the repository.
- For a build server, the token must be allowed to push as well as pull if the workflow verifies or reuses the image.
- After changing scopes or replacing an expired token, log in again on the affected server user.
Check the Linux account used by Coolify
Run docker login as the same account Coolify uses. A login performed as root, a personal user, or another service account is stored in that account’s own ~/.docker/config.json and is invisible to Coolify when it runs Docker under a different user.
Check both sides of a build-and-deploy pipeline
If the image is built on one server and deployed on another, test the push on the build server and the pull on the deployment server independently. Configure the Docker Image application and registry login for the deployment role even when the build job itself completed successfully.
Check every Swarm node
- Resolve the registry hostname from each manager and worker that can receive the service.
- Verify network reachability and any firewall path to the registry.
- Run a manual
docker pullon each node with that node’s Docker user. - Confirm the node has credentials after token rotation.
Separate pull failures from application failures
An unauthorized error occurs before the container starts and points to registry identity, permissions, or reachability. If the pull completes, investigate the image’s entrypoint, environment variables, internal port, domain, and runtime logs instead. Setting a correct Ports Exposes value cannot fix an image that the server was unable to download.
Credential storage and rotation practices
Docker stores registry credentials in the server user’s ~/.docker/config.json, encoded rather than encrypted according to Coolify’s documentation. Restrict access to that account, avoid copying the file into public logs or images, and protect backups that contain it.
- Use a token intended for the required registry operation instead of sharing a personal password.
- Grant pull-only access to deployment servers whenever they never publish images.
- Use separate credentials for build and deployment roles so a compromised deployment host cannot automatically publish images.
- When rotating a credential, log in with the replacement on every machine that pulls or pushes, then remove or invalidate the old credential according to your registry’s controls.
- For Swarm, treat the node list as a rotation checklist; one forgotten worker can fail a later reschedule.
A repeatable deployment checklist
- Publish the image to the intended registry and verify the repository path and tag or digest.
- Give the build server push permission if it publishes the image.
- Give each deployment server pull permission and log in as the Docker account used by Coolify.
- For Swarm, repeat the login and pull test on every eligible node.
- In the project environment, choose + New > Docker Image.
- Enter the complete image reference.
- Open Registries or Servers > [server] > Registries, select Log in, choose the provider or Custom, and save the credentials.
- Set Ports Exposes to the container’s listening port, then configure the domain and runtime settings.
- Deploy and inspect logs. If the pull fails, verify hostname, path, token scope, server user, and node reachability before changing application settings.
- Prefer an immutable version tag or digest when you need to prove that the deployed image content did not change.
Bottom line
Coolify does not use a Git deploy key to access a private container registry. Log in to the registry for the exact server user that runs Docker, and repeat that login for every machine that may push or pull the image. A complete image reference, a correct internal port, and a reachable registry are the remaining requirements; digests or immutable release tags make the resulting deployments predictable.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
