IBM Cloud Docs
Planning your build

Planning your build

Before you start building images with IBM Cloud® Code Engine, learn about the different options you have for your build.

A build, or image build, is a mechanism that you can use to create a container image from your source code. Code Engine supports building from a Dockerfile and Cloud Native Buildpacks.

If you have an image build that exists in a container registry and the image was built with a non-Intel based processor, Code Engine cannot run your container image. Code Engine uses Intel-based processing. You can build your own image if you use Intel processing (x86 processor). You can also choose to let Code Engine handle the build process for you.

Code Engine provides custom resource definition (CRD) methods. For more information, see Source-to-image CRD methods.

Prepare your source location

To give Code Engine access to your source code, you need to make it available in a Git repository or in an accessible location on your local workstation.

Git repository
Store your code in a Git repository, for example in GitHub or GitLab. Your code can be at the top level of your repository or in a subdirectory. If your source repository is not public, you must add access to Code Engine.
Local workstation
Store your code on your local workstation. When you submit a build that pulls code from a local directory, your source code is packed into an archive file and uploaded to your IBM Cloud Container Registry instance. The source image is created in the same namespace as your build image. Note that you can target only IBM Cloud Container Registry for your local builds. You can choose to ignore certain file patterns from within your source code by using the .ceignore file, which behaves similarly to a .gitignore file. For example, entries for a .ceignore file for a node.js application might include node_modules and .npm. For more sample file patterns to ignore, see the GitHub .gitignore repository.

Choose a build strategy

Code Engine can build your container image by using one of following strategies.

Dockerfile

Dockerfile build that uses the BuildKit tool. To use this strategy, add a Dockerfile to your source repository. This Dockerfile describes the steps that are needed to build a container image from your source repository. The Dockerfile might contain steps that copy static files from your sources into the container to be hosted by a web service, for example. It might compile source code that is written in the language of your choice and add the resulting binary to your container image. For more information about Dockerfile builds, see Writing a Dockerfile for Code Engine.

When you pull an image from Docker Hub to use with apps or jobs in Code Engine, be aware of Docker rate limits for free plan (anonymous) users. You might experience pull limits if you receive a 429 error that indicates you reached your pull rate limit. To increase rate limits, you can upgrade your account to a Docker Pro or Team subscription.

Cloud Native Buildpacks

Cloud Native Buildpack that uses Paketo to inspect your source repository and detect which runtime environment that your code is based on and how a container image is built from your sources. Buildpacks make assumptions about the directory structure of your source repositories. For more information about how to structure your source repository correctly, see the samples that are provided for your runtime.

Runtime sample files
Runtime Version Samples
Go 1.22.8 Go samples.
Java 21.0.5 Java samples.
Node.js 20.18.0 Node.js samples.
PHP 8.1.28 PHP samples.
Python 3.10.14 Python samples.
Ruby 3.1.6 Ruby samples.
.NET Core 8.0.403 (.NET Core SDK),
8.0.8 (.NET Core Runtime)		 .NET Core samples.

Images that are built using Cloud Native Buildpacks no longer use the neutral timestamp of Jan, 1st 1980 as their image creation timestamp. The timestamp of the input source is used as the image creation timestamp; for example, the Git commit timestamp of the commit that was used for your build.

The version of a specific runtime for a Paketo buildpack might differ between regions for a brief time whenever an updated version of a buildpack is rolled out to the various IBM Cloud regions.

Determine the size of the build

Code Engine classifies builds into small, medium, large, xlarge, and xxlarge size. The size of the build defines how CPU cores, memory, and disk space are assigned to the build. A smaller build is less expensive, but typically also slower because it uses fewer CPU cores. Also, the memory and disk requirements of your build might cause the build to fail with a smaller size.

Build size values.
Size Dockerfile Buildpacks
small
  • CPU 0.5
  • Memory 2 GB
  • Disk 2 GB
  • CPU 0.5
  • Memory 2 GB
  • Disk 2 GB
medium
  • CPU 1
  • Memory 4 GB
  • Disk 4 GB
  • CPU 1
  • Memory 4 GB
  • Disk 4 GB
large
  • CPU 2
  • Memory 8 GB
  • Disk 8 GB
  • CPU 2
  • Memory 8 GB
  • Disk 8 GB
xlarge
  • CPU 4
  • Memory 16 GB
  • Disk 16 GB
  • CPU 4
  • Memory 16 GB
  • Disk 16 GB
xxlarge
  • CPU 12
  • Memory 48 GB
  • Disk 48 GB
  • CPU 12
  • Memory 48 GB
  • Disk 48 GB

If you are uncertain about which size to choose, consider starting with small or medium. If the build fails due to lack of memory or disk space, or is not fast enough, then switch to larger sizes.

Choose your container image registry

Code Engine pulls source code from a Git repository or a local directory, builds it, and then pushes (uploads) the image to a container image registry.

You can use repositories for your source and registries for your container image that are public or private. You can also choose to specify registry details with a registry secret for your build output, or you can choose for Code Engine to take care of building the image for you from your source and storing the image in IBM Cloud Container Registry with automatic access.

Choose your build method

In the following build options, Code Engine pulls source code from a Git repository or a local directory, builds the container image, and then pushes (uploads) the container image to a registry. You can choose from public or private repositories and registries. If your registry is private, specify registry details with a registry secret for your build output with user-provided access. Or, you can choose for Code Engine to create access to store the image in IBM Cloud Container Registry for you with automatic access.

Create build configurations

In this scenario, Code Engine create a configuration for your build.

Creating a build configuration does not create an image, but instead, creates the configuration to build an image. You can create an image from the configuration by running the build. The build configuration is not validated or used to create an image until the build is run. The build configuration enables multiple subsequent builds of an image, such as when changes are applied to the source repository.

For more information, see the following topics.

After you create your build configuration, you can run it.

Create container image with stand-alone build commands

To learn about how to build your container image with a single Code Engine CLI command and create the container image without creating a reusable build configuration, see Building a container image with stand-alone build commands (CLI).

Build your code and create your workload

When you create a workload from local source code, the source code is packed into an archive file and uploaded to a managed namespace within the IBM Cloud Container Registry instance in your account. The image is also stored in this same namespace.

To build your code and create your workload with a single operation, see the following topics.

Git repository
Local file

Next steps for builds

Looking for more code examples? Check out the Samples for IBM Cloud Code Engine GitHub repo.