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.

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.

Registry and image selection

To deploy a Docker image from a 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:latest

Koyeb will validate that the image and tag you enter is accessible when using the control panel or the CLI.

Image requirements

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.

Also note that an Instance type's local SSD storage affects the maximum container image size it supports. Read container image sizes and storage constraints to learn more.

Redeployment

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.

If you'd like to automatically redeploy container images whenever a new version is uploaded to Docker Hub, consider using the community-contributed koyebdocker-webhook handler (opens in a new tab). It handles events from Docker Hub webhooks to trigger Koyeb deployments.

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, open the Deployment section, 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, open the Deployment section, click the Override toggle associated with the Docker command field and enter a replacement command.

To change the arguments passed to the Docker command, open the Deployment section, 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 Exposed ports and Environment variables and files sections, respectively, and configure the values as needed.