Deploy an app from a Docker image

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 the Koyeb Demo App and deploy the latest version of the koyeb/demo image from the docker hub by using:

docker.io/koyeb/demo:8bbf82ed9ddc

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

Configure your service

• Pick the right amount of resources to run your application
• Select the regions of the world where your service will run
• Define the horizontal scaling and auto-scaling parameters
• Configure the network ports on which your application listens and if the service should be publicly reachable through Koyeb's global load-balancing
• Add environment variables and secrets

To dive deeper, read about the Services Options.

Status of your live Service

Once your Service is deployed, you are redirected to the service page and can access your application:

• 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 instances, their regions, and their status depending on your configuration. Instances 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.