Skip to main content

Buildpacks

Sprintsail uses Cloud Native Buildpacks (CNB) to transform your source code into production-ready OCI container images --- no Dockerfile needed.

How buildpacks work​

Buildpacks follow a detect-then-build pattern:

  1. Detection --- each buildpack in the group examines your source code and opts in or out. A Node.js buildpack detects package.json, a Python buildpack detects requirements.txt, and so on.
  2. Build --- the matched buildpack installs dependencies, compiles code, and configures the runtime.
  3. Export --- the result is packaged as a layered OCI image with separated dependency and application layers for efficient caching.
Source code  →  Detect  →  Build  →  OCI Image
                  ↓
           package.json?
           → Node.js buildpack
           → Install deps (npm ci)
           → Set start command

Paketo Buildpacks​

Sprintsail uses Paketo Buildpacks, the most widely adopted CNB implementation. Paketo provides production-grade buildpacks maintained by the Cloud Foundry Foundation.

Supported languages​

LanguageBuildpackDetection files
Node.jspaketo-buildpacks/nodejspackage.json
Pythonpaketo-buildpacks/pythonrequirements.txt, Pipfile, pyproject.toml, setup.py
Gopaketo-buildpacks/gogo.mod
Javapaketo-buildpacks/javapom.xml, build.gradle, build.gradle.kts
.NETpaketo-buildpacks/dotnet-core*.csproj, *.fsproj, *.sln
Rubypaketo-buildpacks/rubyGemfile
PHPpaketo-buildpacks/phpcomposer.json
Rustpaketo-buildpacks/rustCargo.toml
Nginx (static)paketo-buildpacks/nginxnginx.conf

Auto-detection​

When you run ss push, Sprintsail's build system (kpack) runs the detection phase across all available buildpacks. The first matching buildpack group is used.

Detection priority is determined by the order of buildpacks in the builder. If your project contains files for multiple languages (e.g., a Go backend with a package.json for frontend tooling), you can force a specific buildpack:

ss push --buildpack paketo-buildpacks/go

kpack​

Sprintsail uses kpack to run buildpack builds inside the Kubernetes cluster. kpack provides:

  • In-cluster builds --- no external CI service needed; builds run as Kubernetes pods
  • Image caching --- layers are cached in the internal registry, making rebuilds fast
  • Automatic triggers --- builds can be triggered by source changes or base image updates
  • Build history --- kpack tracks build provenance and metadata

Build resources​

Each build runs in a dedicated pod with allocated resources:

PlanBuild CPUBuild MemoryBuild Timeout
Starter1 core2 Gi10 minutes
Growth2 cores4 Gi20 minutes
Enterprise4 cores8 Gi60 minutes

Base image rebasing​

One of the most powerful features of Cloud Native Buildpacks is rebasing. When the base OS image (e.g., Ubuntu Jammy) receives security patches, kpack automatically rebases your application image onto the patched base --- without rebuilding your application code.

Before rebase:
  [App layer]  →  unchanged
  [Deps layer] →  unchanged
  [OS layer]   →  ubuntu:jammy-20260301  (vulnerable)

After rebase:
  [App layer]  →  unchanged
  [Deps layer] →  unchanged
  [OS layer]   →  ubuntu:jammy-20260401  (patched)

This means:

  • OS-level CVEs are patched automatically within hours
  • No rebuild, no re-test, no redeployment of your code
  • The rebase is a metadata-only operation (seconds, not minutes)
  • Your app is restarted with the patched image via a rolling update

Rebasing is enabled by default for all apps using buildpacks. You can check the current base image:

ss app info my-app --build-details
Build:        #7
Strategy:     buildpacks (paketo-buildpacks/nodejs)
Base image:   paketobuildpacks/run-jammy-base:latest
Base updated: 2026-04-03T08:00:00Z
Rebase:       enabled

Buildpack configuration​

Procfile​

Define process types in a Procfile:

web: node server.js
worker: node worker.js

Environment variables at build time​

Some buildpacks accept configuration through environment variables:

# Set the Node.js version
ss env set my-app --build BP_NODE_VERSION=20.x

# Enable a specific Python version
ss env set my-app --build BP_CPYTHON_VERSION=3.12

# Enable Java native image compilation
ss env set my-app --build BP_NATIVE_IMAGE=true

.buildpacks file​

Specify an ordered list of buildpacks:

paketo-buildpacks/nodejs
paketo-buildpacks/nginx

When to use a Dockerfile instead​

Buildpacks are the best choice for most applications. Consider a Dockerfile when:

  • Your app requires system packages not available in the base image
  • You need precise control over the build process
  • You are building a multi-stage image with custom optimization
  • Your language or framework is not supported by Paketo

You can always switch between buildpacks and Dockerfile strategies:

ss push --strategy buildpacks   # Use buildpacks
ss push --strategy dockerfile   # Use Dockerfile

Next steps​

  • Deploying --- buildpack, Dockerfile, and image deploy strategies
  • Architecture --- how kpack fits into the control plane
  • Networking --- how built images are routed