Everything you need to know about our build system.
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 uses Cloud Native Buildpacks to transform your application source code into an OCI image. We then deploy and run this image on the Koyeb platform.
In this documentation, we will explore the key information needed to understand how the build is performed.
There are 6 steps during the build process:
Once the export step is completed, the final OCI image is deployed in production and live traffic is routed to your service.
The easiest way to deploy is to rely on the default buildpack build commands which are automatically set depending on the application detected in your repository.
If the automated build steps are not enough to properly run your application, you can provide a custom build command. The custom build command is executed after the automated buildpack detection and build. This means that defining a custom build command will not override the automatic buildpack build steps and buildpack build commands will also be executed.
Keep in mind that, depending on the language you use, the buildpack might integrate cleaning steps before executing your build command. This might impact you if you rely on the result of the build performed by the buildpack.
The Koyeb platform provides build logs for all deployments. Build logs are useful to understand what happened during the build stage and easily identify the root cause of build failures.
Each deployment has a unique build log, once a build is completed, no further logs will appear. Build logs are stored for 30 days.
You can easily reproduce the different steps of the build using the pack CLI.
This is useful to troubleshoot and for advanced use cases.
To install the pack CLI, you can read the official installation guide here.
Inside the repository, to build using pack, run:
pack build -B koyeb/builder YOUR_BUILDPACK_IMAGE_NAME
This command will perform a build of your application using the koyeb/builder
builder and will generate an OCI image named with the name you passed to the pack CLI.
You can then run the container with your application:
docker run --rm -p 8080:YOUR_APP_LISTENING_PORT YOUR_BUILDPACK_IMAGE_NAME
For the complete Pack CLI references, please check out the Buildpacks documentation
To ensure maximal compatibility, we currently use a builder derived from
the heroku/buildpacks:20 builder.
There are two options to define the command used to launch your application:
Procfile.In some cases, a default run command might be set by the buildpack. Refer to the language-specific section to know more. If there is both a Procfile and a run command defined, the run command will take precedence over the Procfile.
A Procfile is a file you create at the root of your application repository to
define how to launch your application.
Procfiles on Koyeb contain the command needed to run the app your production prefixed by web: like:
web: <command>
For instance to launch your application with yarn start:production, the Procfile will be:
web: yarn start:production
If no Procfile is present in your application repository, 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
Node.js applications are detected when the application contains a package.json file in the root directory of the repository.
Currently, supported versions of Node.js are 16.x, 18.x, and 19.x.
To specify the Node.js version to use, the engines section must be present to specify the Node.js version to use in your package.json.
{ ... "engines": { "node": "16.x" } ... }
If no version is specified in your package.json file, node 18.x will be used.
Important: If you set the NODE_ENV environment variable to production, modules listed in devDependencies of your package.json will be removed once the build step has completed successfully. To keep all modules listed in both dependencies and devDependencies at runtime when setting NODE_ENV to production, add the following environment to your Service configuration:
NPM_CONFIG_PRODUCTION=false if you use npmYARN_PRODUCTION=false if you use yarnPython applications are detected when the application contains a requirements.txt or setup.py file in the root directory of the repository.
Currently, supported versions of Python are python-3.11.2, python-3.10.10, python-3.9.16, and python-3.8.16,
To specify the Python version to use, add a runtime.txt file in the root directory of your repository with one of the versions mentioned above. For instance, to use Python 3.8, your runtime.txt file must contain all three version number components (major, minor, and patch):
python-3.11.2
If no version is specified, python-3.11.2 will be used.
Go applications are detected when the application contains at least one of the following:
go.mod at the root of the projectGodeps/Godeps.json file, identifying the application as being managed by godepvendor/vendor.json file, identifying the application as being managed by govendorsrc directory, which has subdirectories, contains one or more .go files, identifying the application as being managed by gb.By default, the version used to build your application is fetched from your dependency manager metadata file. You can change the version by updating the appropriate metadata file or setting the $GOVERSION environment variable, depending on the dependency manager you use.
Ruby applications are detected when the application contains at least one of the following:
config.ru indicates a Rack applicationconfig/environment.rb indicates a Rails 2 applicationconfig/application.rb containing the string Rails::Application indicates a Rails 3 applicationBy default, your application is built using the Ruby version defined in your Gemfile.
If your Gemfile does not contain a ruby entry, your app will be built using Ruby (MRI) 3.1.2.
PHP applications are detected when the application contains a composer.json file in the root directory of your repository.
Even if your application does not require Composer to run, the file must be there to indicate your app is a PHP application and contain the following content.
{}
If no PHP version is specified on your composer.json file, your application will be built using the PHP 8 runtime. To specify a specific runtime, the following instruction must be present in your composer.json file:
{ ... "require": { "php": "^8.2" } ... }
Never use a specific version like 8.2.3, instead, use the ^ or ~ next significant release operators to ensure that you get appropriate updates upon push as they become available.
The default build system for Java applications when using heroku/buildpacks:20 builder is Maven. Java applications are detected when a pom.xml file is detected inside the root of your directory.
You can use a specific Java version by creating a file called system.properties in the root level of your application with the following content:
java.runtime.version=19
Accepted major version values are 1.8, 11, 13, 15, 17, and 19.
If you do not specify a Java version, the default value is set to 1.8