Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Builds and Pipelines

Source-to-Image (S2I)

Understand how Source-to-Image turns application source into a runnable image with builder images, assemble and run scripts, and how to customize or create your own builder.

Source-to-Image (S2I) is the way OpenShift builds an image when you give it only source code. There is no Dockerfile to write. A builder image that knows how to build a particular language, such as Node.js, Python, Java, PHP, Ruby, Go or .NET, takes your source, builds it and produces a ready-to-run application image.

The benefit: developers focus on code, and platform teams control the base image, patches and security in one place.

How S2I works

flowchart LR
  S["Source code<br/>from Git or upload"] --> B["Builder image<br/>e.g. nodejs"]
  B -->|"assemble script"| A["Application image<br/>code + runtime"]
  A --> R["Registry / ImageStream"]
  R -->|"run script"| P["Running Pod"]

Figure: the builder image runs its assemble script on your source; the resulting image starts with its run script.

Steps inside a build:

  1. OpenShift starts a build Pod from the builder image.
  2. The source is injected into the container (for example into /tmp/src).
  3. The builder's assemble script runs: install dependencies (npm ci), compile, copy the result to the app directory.
  4. OpenShift commits the container as a new image, setting its start command to the builder's run script.
  5. The image is pushed to the registry, and typically to an ImageStream tag.

Because the final image is the builder image plus your build output, it contains the runtime your app needs. For compiled languages you can use runtime images or multi-stage tricks to keep the final image small.

Using S2I from the CLI

Terminal
oc new-app nodejs~https://github.com/example/web-app.git --name=web
oc new-app https://github.com/example/web-app.git --name=web
oc new-build --image-stream=nodejs:20-ubi9 --binary --name=web
oc new-app python:3.12-ubi9~https://github.com/example/py-app.git

<builder>~<source> names the builder explicitly. Without it, oc new-app detects the language from files in the repository (package.json, requirements.txt, pom.xml, composer.json, go.mod...). Available builders are in the openshift project as ImageStreams:

Terminal
oc get imagestreams -n openshift
oc new-app --list
oc describe is nodejs -n openshift

The exact tags (language versions) change with each release; always list them on your cluster instead of copying old tutorials.

Configuring a build with environment variables

Most builders read environment variables. You set them on the BuildConfig, not in the code:

Terminal
oc set env bc/web NPM_MIRROR=https://registry.example.com/npm/
oc set env bc/web --list

Typical examples: a package registry mirror, the application's start script, the Maven goals to run, or whether to run in production mode. The builder's documentation lists which variables it understands. A second type, runtime environment variables, belongs on the Deployment.

You can also put variables in a file named .s2i/environment in your repository, which keeps build settings with the source:

TEXT
NPM_RUN=build
NODE_ENV=production

Overriding the scripts

Don't like the builder's default assemble? Put your own scripts in .s2i/bin/ in the repository:

TEXT
.s2i/
  environment
  bin/
    assemble
    run

A custom assemble can call the original one (/usr/libexec/s2i/assemble) and then add steps. This is a flexible way to adapt a builder without owning an image.

Incremental builds and chained builds

Some builders support incremental builds: the previous image's cached artifacts (such as node_modules or Maven's repository) are reused to speed up the next build when incremental: true is set in the strategy. Another approach, chained builds, builds a heavy artifact in one image and copies only what is needed into a lean runtime image.

Creating your own builder

If no builder exists for your stack, the s2i tool can scaffold one:

Terminal
s2i create my-builder ./my-builder
cd my-builder && ls s2i/bin
s2i build ./app-src my-builder:latest my-app --loglevel 2

You write a Dockerfile that installs the runtime, and the assemble, run and optionally save-artifacts and usage scripts. The result is an ordinary image you push to a registry or ImageStream.

S2I vs Docker strategy

Question S2I Docker
Who controls the OS and runtime? The platform's builder image You, in the Dockerfile
Need a Dockerfile? No Yes
Patch base for everyone at once Easy: update the builder Must update each Dockerfile
Full control over layers Limited Full
Best for Standard stacks, many teams Custom stacks, existing Dockerfiles

Neither is "better"; the choice depends on how much control the team needs.

Stand-in: language detection

oc new-app looks at files to choose a builder. The stand-in below does the same with a small table. Real detection has more rules and a precedence order of its own.

Python Stand-in: pick a builder from files

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: assemble and run

Python Stand-in: what assemble and run do

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Troubleshooting S2I builds

  • "Failed to fetch": Git URL wrong or private; add a source secret.
  • Build runs out of memory: set resources.limits.memory higher on the BuildConfig.
  • Wrong language version: choose a different tag, for example nodejs:20-ubi9.
  • App starts then exits: the builder's run script cannot find your entry point; set the start variable documented for that builder, or add .s2i/bin/run.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which script in a builder image turns source into a built application?

    assemble installs dependencies, compiles and places the application. run starts it when the container runs.
  2. 2. What does the notation nodejs~https://git.example/app.git mean?

    builder~source names the builder image explicitly.
  3. 3. Where can you put custom assemble or run scripts in your repository?

    .s2i/bin/assemble and .s2i/bin/run override or extend the builder's scripts.
  4. 4. What is a key advantage of S2I for a platform team?

    Because apps build on a shared builder, a patched builder image is picked up on rebuild.

Summary

  • S2I builds an application image from source plus a builder image, with no Dockerfile.
  • The builder's assemble script builds; its run script starts the app.
  • oc new-app builder~repo picks a builder; otherwise OpenShift detects the language.
  • Configure builds with environment variables, .s2i/environment and .s2i/bin scripts.
  • Choose S2I for standard stacks and the Docker strategy when you need full control.

Next: ImageStreams and Tags