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:latest

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

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 Docker commands and arguments

To override the default command configured for a Docker image, expand the Docker settings section on the Service configuration page. Click the Override toggle associated with the Docker command field and enter the new 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 change the ports exposed on the container or add environment variables, expand the Advanced section and configure the values as needed.

Scala Deploy with GitHub