How We Build from Git

When a Koyeb Service is connected to a git repository, the build and deployment process will be performed each time a change is detected on your branch or if you manually trigger a redeploy action.

Koyeb can use either of the following methods to build your projects:

• Building from a Dockerfile: Builds your project based on a provided Dockerfile in your git repository. This gives you complete control over your dependencies and the environment for your application.
• Building with Buildpacks: Analyzes your application source code and transforms it into a runnable image with language-specific build and installation processes.

Once we have an image, we deploy and run them on the Koyeb platform.

In this documentation, we will explore the key information needed to understand how the build is performed.

The Dockerfile build process

The Dockerfile build process evaluates a Dockerfile within your project's repository to generate a container image. Koyeb uses standard tools to build the container image, so any valid Dockerfile will be processed in the same way as it would locally. No special instructions are required.

During the configuration process, you can provide an alternative location for your Dockerfile if it isn't found in the repository root. If you'd like to modify how the generated image runs, you can also provide entrypoint, command, and argument values to override the settings defined by the Dockerfile. For multi-stage builds (opens in a new tab), you can choose the build stage that you'd like to produce and run for your Service.

You can learn more about modifying the runtime configuration of Dockerfile-built Services on our page on deploying from GitHub.

The buildpack build process

The buildpack build process uses cloud native buildpacks (opens in a new tab) to turn your application code into an OCI image (opens in a new tab). We use the Koyeb buildpack builder (opens in a new tab) to analyze your project files and generate images.

Buildpack build steps

There are 6 steps during the build process:

1. Clone: First, your git repository is cloned.
2. Analyze: Next, the metadata associated with any previously built images is examined to potentially optimize further stages of the process.
3. Detect: The detector selects the buildpacks to use during the build phase.
4. Restore: Layers from the cache are restored if an existing OCI image has already been created for the repository.
5. Build: Your application source code is transformed into runnable artifacts that can be packaged into a container.
6. Export: The final OCI image of your application is created and pushed to the Koyeb Container Registry.

Once the export step is completed, the final OCI image is deployed to production and live traffic is routed to your Service once health checks complete successfully.

Build command

The easiest way to deploy is to rely on the default buildpack build commands that are automatically set based on the application type detected in your repository.

If the automated build steps are not enough to properly run your application, you can provide a custom build command.

Build locally

You can easily reproduce the different steps of the build using the pack CLI. This is useful for troubleshooting and for advanced use cases.

To install the pack CLI, follow the steps for your platform in the official installation guide (opens in a new tab).

Within your repository run the following command to build using pack:

pack build -B koyeb/builder <YOUR_BUILDPACK_IMAGE_NAME>

This command will build your application using the koyeb/builder builder (opens in a new tab) and generate an OCI image with the name you provided.

Afterwards, you can run the container with your application by typing:

docker run --rm -p 8080:<YOUR_APP_LISTENING_PORT> <YOUR_BUILDPACK_IMAGE_NAME>

For the complete Pack CLI reference, please check out the Buildpacks documentation (opens in a new tab)

To ensure maximum compatibility, we currently use a builder derived from the heroku/buildpacks:20 builder.

Execution, run command, and the Procfile

There are two ways to define the command used to launch your buildpack-built applications:

1. With the run command filed defined in the Service configuration.
2. In your repository itself with a Procfile.

In some cases, a default run command might be set by the buildpack. Refer to the documentation for your project's language to learn more. If a Procfile is present and a run command is defined, the run command will take precedence over the Procfile.

Procfile

A Procfile is a file at the root of your application repository that defines how to launch your application.

The Procfile format supported by Koyeb consists of a web: prefix followed by the command to execute to run the application in production:

web: <YOUR_APPLICATION_RUN_COMMAND>

For example, to launch your application with yarn start:production, the Procfile would look like this:

web: yarn start:production

If your repository does not have a Procfile and you do not provide a run command, your application may fail to start properly and an error will appear in the logs printing the following:

failed to launch: determine start command: when there is no default process a command is required

Supported buildpack languages

We currently support building applications with the following languages. Consult the language-specific pages for more information language-specific behavior.

• Node.js
• Python
• Go
• Ruby
• PHP
• Java
• Scala

Build logs

The Koyeb platform provides build logs for all git-driven Deployments. Build logs are useful for understanding what happened during the build stage and can help identify the root cause of build failures.

Each Deployment has a unique build log. Once a build is completed, no further build logs will appear (runtime logs will still be generated). Build logs are stored for 30 days.