Pre-Built Docker Images
Koyeb supports running applications using Docker images uploaded to public or private container registries. Docker images allow you to package your project's system dependencies along with its code so that you can control the exact environment it will operate in.
This document describes deploying pre-built container images stored in public or private registries.
To learn more about building and deploying a Docker container from a repository's Dockerfile, read using the Dockerfile builder.
To deploy pre-built Docker images, choose Docker as your deployment method when creating services in the Koyeb control panel (opens in a new tab) or with the Koyeb CLI.
Deploy from a public registry
To deploy a Docker image from a public registry, provide the complete domain and path to Docker image. The general format should look like this:
<REGISTRY_DOMAIN>/<PATH_TO_IMAGE>:<OPTIONAL_IMAGE_TAG>For example, to deploy the latest version of the koyeb/demo app from Docker Hub (opens in a new tab), you would specify the image like this:
docker.io/koyeb/demo:latestIn the Koyeb control panel (opens in a new tab), the Image and Tag are two separate fields:
- Image:
docker.io/koyeb/demo - Tag:
latest
Note: The container image associated with a Service must be accessible at the time of deployment. If the image is unpublished or otherwise unavailable, future deployments will fail.
Koyeb does not automatically redeploy Services based on image changes in container registries. To use the new version of an image, you must explicitly redeploy the Service. Koyeb will automatically use the newest version of the provided image and tag combination when new deployments are triggered for other reasons like configuration changes or maintenance operations.
Deploy from a private registry
To deploy an image from a private registry, you must first create a Secret with the authentication details for your private registry.
The Koyeb control panel includes a form in the App and Service creation views to automatically create a Secret with the right format. If you are using the Koyeb control panel, click the Private image toggle below the Docker image fields and then select Create secret from the Registry configuration secret drop-down to access the form.
If you need to use a provider not listed in these views or need to create the secret manually, check our Private Container Registry Secrets documentation.
Custom deployment settings
To override the default Docker and deployment settings, expand the Deployment settings section on the Service configuration page.
To override the default entrypoint (opens in a new tab) configured for a Docker image, click the Override toggle associated with the Docker entrypoint field and enter the new entrypoint.
To override the default command (opens in a new tab) configured for the Docker image, click the Override toggle associated with the Docker command field and enter a replacement command.
To change the arguments passed to the Docker command, click the Override toggle associated with the Docker args field and enter new arguments.
To run the Service container in privileged mode (opens in a new tab), click the Privileged toggle. This advanced feature is useful when you need elevated system privileges like, for example, to start a Docker daemon within the container.
To change the ports exposed on the container or add environment variables, expand the Advanced section and configure the values as needed.