To deploy an existing container image on Coolify, create a Docker Image resource inside a project and environment, enter the image repository with either a release tag or a SHA256 digest, set the container’s internal listening port, then save and deploy. Coolify pulls that reference on the selected server, applies the runtime settings you provide, and starts the container; it does not clone source code or build an image for this resource type.
Antihost offers VPS plans with one-click Coolify, NVMe storage and a 14-day free trial.
You need dashboard access, at least one connected server, and a running Coolify proxy. The walkthrough below covers public and private registries, tag selection, ports, domains, environment variables, storage, health checks, reproducibility, and the failure modes that most often make a deployment appear broken.
As an Amazon Associate I earn from qualifying purchases.
What a Coolify Docker Image deployment does
A Docker Image application is the “pull and run” deployment path. The image already exists in a registry such as Docker Hub or the GitHub Container Registry (GHCR). Coolify instructs Docker on the deployment server to pull the specified image, creates a container from it, and supplies runtime configuration such as environment variables, ports, storage, networks, restart behavior, and health checks.
The image remains the source of the filesystem and default process. Coolify’s settings are layered on when the container is created or replaced. Changing a Coolify setting does not modify the image stored in the registry.
#1 Best Overall
This differs from the other common resource types:
| Deployment path | What Coolify does | Typical scope | Reference reproducibility | Configuration ownership |
|---|---|---|---|---|
| Docker Image | Pulls an existing image and runs it | One container | Release tag or digest; mutable tags can change | Image defaults plus Coolify runtime settings |
| Dockerfile | Builds an image from source and a Dockerfile, then runs it | Usually one application container | Depends on source revision, base images, and build inputs | Build instructions plus Coolify runtime settings |
| Docker Compose | Creates the services described in a Compose configuration | Multiple cooperating containers are possible | Depends on each referenced image or build definition | Compose file plus Coolify runtime settings |
Choose Docker Image when a registry build is already complete and you do not need Coolify to compile source code or coordinate a multi-service Compose stack.
Prerequisites and information to collect
Before opening the resource form, make sure the following are ready:
Recommended Free Tools
- Coolify access: you can open the target project and environment and have permission to create and deploy resources.
- A connected server: at least one server is registered with Coolify and available as a deployment target.
- A running Coolify proxy: the proxy is required when you want Coolify to route a domain to an HTTP container. Coolify’s first-app walkthrough demonstrates the basic setup with
nginx:alpinelistening on port 80. - Complete image reference: collect the registry host (when needed), repository path, and the release tag you intend to deploy, for example
ghcr.io/example/api:1.4.0. - Or a fixed digest: if you want content-addressed deployment, obtain the image’s 64-character SHA256 value.
- Internal listening port: determine the port on which the process listens inside the container. This is not automatically the same as a public host port.
- Registry credentials: for a private image, configure credentials on every server that may pull the image, not only on the server used for your first deployment.
Also decide whether the service needs a public domain, environment variables, persistent data, a health check, or CPU and memory limits. These choices affect container operation but do not change the image itself.
Step-by-step: create and deploy the Docker Image resource
-
Open the target project and environment
Sign in to Coolify, open the project that should own the application, and select the environment where it will run. Confirm that the environment can reach the connected server you prepared.
-
Choose the Docker Image resource
Select + New → Docker Image. Do not choose a Dockerfile or Compose resource for an image that is already published and ready to run.
-
Enter the repository and version
Enter the full image reference, such as
ghcr.io/example/api:1.4.0. If the form separates the repository from the version, enter the repository and complete either the Tag field or the SHA256 Digest field.Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.Use one identification method only. When you use the digest field, enter the 64-character hexadecimal digest without the
sha256:prefix. Do not fill in both Tag and SHA256 Digest for the same deployment. -
Set the internal port in General
Open General and set Ports Exposes to the port where the process listens inside the container. Docker Image applications start with port 80 as the default, so change this value when your application listens on another port, such as 3000 or 8080.
The value tells Coolify which container port should receive traffic. It is not a declaration that the application must bind to a particular public host port; the proxy and container networking handle that routing.
-
Add a domain when the service is public
If users should reach the service over HTTP or HTTPS, add its domain in the resource settings and make sure DNS points to the server that will receive traffic. The Coolify proxy uses the configured domain to route requests to the exposed container port. A private worker, queue, or internal API may not need a domain at all.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, 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 minuteSpecial offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Configure runtime settings
Add environment variables, persistent storage mounts, health checks, restart behavior, networks, and resource limits as required by the image. These values are supplied when Coolify creates the container. They do not rebuild or edit the registry image.
-
Save and deploy
Select Save, then Deploy. Open Deployment Logs and verify that the expected repository and tag or digest were pulled and that the container started. Test the configured domain, if one exists, and inspect application logs for startup errors.
Choosing a tag or a SHA256 digest
Version tags for readable releases
A tag such as 1.4.0 is easy to recognize in a deployment list and works well when your release process never retargets that tag. A human can immediately see which application version is intended.
Digests for fixed image content
A SHA256 digest identifies one exact image manifest. If the registry later publishes another image under the same human-readable tag, a digest still resolves to the original content. This is useful when you need repeatable production rollouts, an auditable release record, or a dependable rollback target.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Why latest can surprise you
latest is a mutable tag. It can point to different content over time, and restarting a Docker Image application pulls the saved reference again. A restart can therefore run newer bytes even when no Coolify field changed. Prefer an immutable release tag under a policy that prevents retagging, or use a digest when exact content matters.
| Reference | Readable in the dashboard | Can resolve to new content later | Best fit |
|---|---|---|---|
Release tag, for example 1.4.0 |
Yes | Only if the registry tag is moved | Normal versioned releases |
Mutable tag, for example latest |
Yes | Yes | Development or deliberately floating deployments |
| SHA256 digest | Less convenient to read | No, it identifies fixed content | Reproducible production deployments and rollbacks |
Ports, domains, and container networking
The most common networking mistake is entering the host-facing port instead of the process’s internal container port. If the application binds to port 3000 inside the image, set Ports Exposes to 3000 even if users will access it through an HTTPS domain on the standard public port.
The process must also bind to an interface reachable from the container network. An application that listens only on its own loopback interface can fail behind the proxy even when the numeric port is correct. The image’s documentation or startup configuration should tell you the bind address and port.
For an HTTP resource, the proxy receives the domain request and forwards it to the configured container port. Check all three pieces when a domain fails: DNS reaches the correct server, the application is listening on the expected internal port, and the Coolify resource exposes that port.
Free tools Windows power users keep installed
One-click scans. No signup required.
Private registries and pull credentials
A public image can be pulled without authentication. A private Docker Hub repository, GHCR package, or another private registry requires credentials that Docker can use on the deployment server. Configure those credentials in Coolify according to the registry integration available in your installation, then verify that every possible deployment server has access.
Credential coverage matters when you move a resource, add a second server, or redeploy after a failure. A login that exists on one machine does not automatically authenticate Docker on another machine. Keep the account limited to the read permission needed to pull images, and rotate it using your normal secret-management process.
Environment variables and other runtime configuration
Environment variables
Environment variables are stored separately from the running container. Add or edit them in the resource’s environment settings, save them, and then restart or redeploy so Coolify recreates the container with the new values. A running process cannot see a changed variable until it is started with that new environment.
If a value is needed while an image is being built, a Docker Image resource cannot provide that build-time input because no build occurs. Build-time configuration belongs in the image creation workflow; runtime configuration belongs in Coolify.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsPersistent storage
The container filesystem is replaceable. A new deployment, image update, or container recreation can discard files written only inside that layer. Mount a configured persistent volume or host path for databases, uploads, caches that must survive replacement, and other stateful data. Confirm the path expected by the application before deploying so the mount does not hide files the image needs at startup.
Restart behavior, networks, and limits
Set restart behavior appropriate to the service, attach additional networks only when the application must communicate with other resources, and define CPU or memory limits when you need predictable resource boundaries. These options control how Docker runs the container; they do not alter the image’s packaged files or default command.
Health checks that work inside the image
Coolify-managed health checks can be HTTP or CMD. An HTTP check runs from inside the application container, so the final image must contain the command-line tool used by the check, such as curl or wget. A check that calls curl in an image without curl will fail even if the application itself is healthy.
Configure the endpoint and port for the process inside the container, not the public domain’s external port. After enabling, changing, or disabling a check, restart or redeploy so Coolify recreates the container with the new check configuration.
A Dockerfile health-check pattern looks like this:
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3
CMD curl --fail http://localhost:3000/health || exit 1This example assumes the process listens on port 3000, exposes /health, and includes curl. Replace both the endpoint and port with values supported by your image. The timing values are an example pattern, not a universal requirement.
Verify a deployment before calling it successful
- Read Deployment Logs: confirm that the intended repository and tag or digest were pulled, rather than an unexpected default.
- Check startup logs: look for a successful bind message, migrations that completed, and the absence of immediate crash-and-restart cycles.
- Test the service: open the configured domain or call the service from an allowed network. Verify an application-level response, not merely an open TCP connection.
- Inspect the health state: if a check is enabled, wait for the configured startup period and confirm that it becomes healthy.
- Confirm persistence: write a harmless test value where appropriate, redeploy, and verify that data stored on the configured volume remains available.
For a basic smoke test, deploy nginx:alpine, leave the internal port at 80, and open the generated test domain from Coolify’s first-app flow. This isolates proxy, DNS, and basic container-start issues from application-specific configuration.
Best Value
Troubleshooting common failures
The image pull fails
- Check the registry hostname, repository path, and spelling.
- Confirm that the tag exists or that the digest is exactly 64 hexadecimal characters and was entered without
sha256:. - For a private image, verify read credentials on the specific server selected for deployment.
- Read the pull error for authorization, rate limiting, or manifest-platform details before changing unrelated runtime settings.
The container starts but the domain is unreachable
- Confirm that Ports Exposes matches the process’s internal listening port.
- Check the application bind address and startup logs.
- Verify that DNS points to the intended server and that the domain is attached to this resource.
- Use a direct application log check to distinguish a proxy route problem from an application crash.
The health check stays unhealthy
- Run the endpoint test from inside the container’s own network context.
- Confirm that the path returns success only after the application is ready.
- Install or include
curlorwgetin the final image when the check command requires it. - Restart or redeploy after changing the check so the container receives the new definition.
A changed variable has no effect
Save the variable and restart or redeploy the resource. Coolify must recreate the container for the process to receive a changed environment.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
A restart runs unexpected code
Inspect whether the resource uses a mutable tag such as latest. Replace it with a version tag governed by an immutable release policy or pin the exact digest, then deploy the intended reference.
Updating and rolling back safely
Updating to a new release
For a tagged workflow, change the image tag to the new release and deploy. For a digest workflow, replace the digest with the new content address and deploy. Read the deployment and application logs before directing traffic to the new container.
Rolling back
Roll back by restoring the previous known-good tag or digest and deploying it again. A digest is especially useful when a tag may have been moved, because it continues to identify the earlier image content.
Changing runtime settings
Port, environment, storage, health-check, network, and resource-limit changes take effect when Coolify restarts or redeploys the container with those settings. Treat a settings-only change as an operational change even though the image reference stays the same.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Operational checklist
- Project and environment are correct.
- Deployment server is connected and has registry access.
- Image repository is complete and the tag or digest is valid.
- Only one of Tag or SHA256 Digest is filled in.
- Digest is 64 hexadecimal characters without the
sha256:prefix. - Ports Exposes equals the process’s internal listening port.
- Domain and DNS are configured when public access is required.
- Secrets and environment variables are saved before deployment.
- Persistent data uses configured storage rather than the replaceable container layer.
- Health-check commands exist in the final image and target the correct internal endpoint.
- Deployment Logs and application logs show the expected image and a ready process.
Frequently asked questions
Does Coolify build my Docker Image resource?
No. This resource type pulls an image that is already in a registry and runs it. Use a Dockerfile resource when Coolify must build from source.
Can I enter both a tag and a digest?
No. Enter the repository with either a tag or a SHA256 digest. When using the separate digest field, omit the sha256: prefix.
Why does Coolify default to port 80?
Docker Image applications start with port 80 as the default exposed value. Change it in General when the process listens elsewhere inside the container.
Will changing an environment variable update a running container?
Not immediately. Save the variable and restart or redeploy so Coolify recreates the container with the new environment.
Why can an HTTP health check fail even though the app opens in a browser?
The check runs inside the container and depends on tools such as curl or wget being present there. It also must use the application’s internal port and a readiness endpoint that returns success.
