Deploy an app from a Docker image

Everything you need to know to deploy an application using a Docker image on Koyeb.

Koyeb natively allows you to run your own, pre-built container images. With containers, you can embed all the system dependencies you need.

Deploying a containerized app on Koyeb only takes a minute, in this guide we will explain how-to:

  1. Deploy the first service on Koyeb using a Docker image
  2. View the live status of your app and services

Deploy the first service of your App

Koyeb provides the notion of Apps, which contain all the components needed to run your applications, including the ability to run one or more Docker-based Services per App. You can read more about Koyeb Apps in the Apps Overview documentation.

When you deploy a Service on Koyeb, you have a few customizable settings. All settings can be transparently upgraded after the initial creation. Let's explore our options.

Docker image and custom commands

The first step is to enter the full URL to the Docker image you want to use. We recommend using a unique tag to simplify upgrades and deployment traceability.

If needed, you can easily override the default command and arguments of your Docker image.

Deploy from a public registry

To deploy a Docker image from a public registry, simply reference the Docker image with the complete path to it, including the domain. If your registry is hosted on registry.domain.tld, the value will look like registry.domain.tld/PATH_TO_IMAGE:TAG.

You can give it a try with an HTTP debug server and deploy the latest version of the kennethreitz/httpbin image from the docker hub by using:

Deploy from a private registry

To connect to your private registry, the Koyeb platform needs to be able to access the registry and you will need to create a secret with the login information for your registry. We use secrets to store these credentials and provide an easy-to-use form in the app and service creation views to automatically create a secret with the right format. 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.

Container size

The second step is to select the correct amount of resources for an instance of your application. The recommended way to scale your application is to enjoy the seamless horizontal scaling provided by the Koyeb platform but some applications require a significant amount of resources for a single instance to perform well.

Check out our pricing page to explore our container sizes. We provide options with up to 64GB of RAM, 32vCPU, and 640GB of SSD, and even more for demanding applications.


You have the possibility to select in which region of the world your services will run. You can select one or more regions in which your service will be available. End-users will automatically be redirected to the nearest region where your service is running thanks to our global edge network.

Horizontal scaling

You can easily define the number of simultaneous containers running per region for your Service. If you select a different minimum and maximum, the number of simultaneous containers will be autoscaled between these values depending on the number of incoming requests.


By default, all network ports are blocked, you need to explicitly define on which network port your application listens for incoming traffic. Exposing ports is needed for public and private services receiving incoming requests but not for workers. The protocol and ports are also used to perform health checks.

To make your Service reachable for everyone through the internet, select Expose publicly. Koyeb will automatically make your service available at https://<appname-orgname><path>. All requests will be proxyfied to the port you selected and load-balanced between your nodes.

Environments variables

Environments variables can be used to configure your app. Secrets can be exposed to your app through environment variables.

Status of your live Service

Once your Service is deployed, you are redirected to the service view. Your service is accessible:

  • via public URLs if you decided to expose it publicly
  • via a private domain through the service mesh from other Services of your App

You will see all the individual nodes, their regions, and status depending on your configuration. Nodes might be detected as unhealthy due to a configuration issue.

If your deployment is failing, check the logs panel and refer to our troubleshooting deployments guide.