Buildpack for Containers

The buildpack packaging type (BuildpackImagePackaging) builds a container image from a project directory without a Dockerfile. Stacktape detects the language, framework, package manager, tool versions and start command from the project's own files, builds the image and uploads it to a managed ECR repository.

Detection and the build plan come from Railpack, an open-source builder by Railway. Stacktape runs it for you; you do not install or configure it.

It applies to web services, private services, worker services, multi-container workloads, batch jobs and AgentCore runtimes.

When to use

Use buildpack when:

  • The service is not a single JavaScript or TypeScript entry file. Python, Go, Rust, Java, PHP, Ruby, .NET and Elixir services, and Node.js frameworks with their own build output such as Next.js, Nuxt, Remix or Astro.
  • The project follows its ecosystem's conventions. A lockfile, a standard dependency file and a conventional start script are enough. You do not need to write or maintain a Dockerfile.

Use another packaging type when:

  • A Node.js service has one entry file. js-bundle bundles it into a smaller Alpine image.
  • You need full control over the image. Use dockerfile for a specific base image, GPU drivers, multi-stage builds or a custom entrypoint.
  • The image already exists. Use prebuilt-image.

Basic example

All properties are optional. sourceDirectoryPath defaults to the directory of the Stacktape configuration file.

export default defineConfig(() => {
  const api = new WebService({
    packaging: new BuildpackImagePackaging({
      sourceDirectoryPath: './api'
    }),
    resources: {
      cpu: 0.5,
      memory: 1024
    }
  });

  return {
    resources: { api }
  };
});

A web service must listen on the port in the PORT environment variable. Most detected start commands already do. If yours does not, set startCommand, for example uvicorn app.main:app --host 0.0.0.0 --port $PORT.

What is detected

Stacktape reads these files in sourceDirectoryPath:

  • Dependency files and lockfiles: package.json (including packageManager and engines), package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock, pyproject.toml, requirements.txt, Pipfile, Cargo.toml, go.mod, Gemfile, composer.json, mix.exs, *.csproj, deno.json and gleam.toml.
  • Version files: .nvmrc, .node-version, .python-version, .tool-versions, mise.toml and rust-toolchain.toml.
  • Procfile: overrides the detected start command.
  • railpack.json: applied on top of the detected build. The railpackConfig property in the Stacktape configuration takes precedence over this file.

Files matched by .dockerignore in the source directory are left out of the build.

Supported languages

LanguagePackage managers and build toolsFrameworks with detected build and start commands
Node.jsnpm, pnpm, yarn, bunNext.js, Astro, SvelteKit, Remix, Nuxt, TanStack, Nx, Angular. Vite and Create React App single-page apps are served by Caddy.
Pythonpip, uv, poetry, pdm, pipenvDjango, FastAPI, Flask
PHPComposerLaravel, served by FrankenPHP
RubyBundlerRails
GoGo modules
RustCargo
JavaMaven, Gradle
.NETdotnet
ElixirMixPhoenix
Deno, Gleam
OtherC/C++, static sites, shell scripts

If a project uses a layout the detection does not recognize, set startCommand and, if needed, buildCommand.

Commit the project's lock file. Ruby and Elixir builds fail without Gemfile.lock or mix.lock, and a Bun build fails when bun.lock does not match package.json.

Properties

Every property overrides one part of the detected build. A project that follows its ecosystem's conventions needs none of them.

PropertyPurpose
sourceDirectoryPathDirectory to build, relative to the Stacktape configuration file. Default: .
startCommandCommand that starts the app. Runs through bash -c in /app.
buildCommandCommand that builds the app after dependencies are installed.
installCommandCommand that installs dependencies. The default is the package manager's locked install, such as npm ci or uv sync --locked.
packagesTool versions installed by mise, such as { node: '22', pnpm: '10' }. Use it when the project has no version file.
aptPackagesDebian packages installed with apt, available during the build and at runtime.
buildEnvironmentEnvironment variables for the install and build commands, passed as Docker build secrets.
railpackConfigA railpack.json configuration merged over the detected build.

Start, build and install commands

packaging: new BuildpackImagePackaging({
  sourceDirectoryPath: './api',
  installCommand: 'uv sync --locked --no-dev',
  buildCommand: 'python manage.py collectstatic --noinput',
  startCommand: 'gunicorn --bind 0.0.0.0:$PORT config.wsgi'
}),

Tool versions and system packages

packages sets tool versions by mise tool name, for example node, python, go, rust, ruby, php, java or pnpm. A version file in the project, such as .nvmrc or .python-version, does the same and also works outside Stacktape.

aptPackages installs Debian packages. Common libraries, such as libpq for PostgreSQL clients, are installed automatically when a dependency that needs them is detected.

packaging: new BuildpackImagePackaging({
  sourceDirectoryPath: './renderer',
  packages: { node: '22', pnpm: '10' },
  aptPackages: ['ffmpeg']
}),

Build environment variables

buildEnvironment makes variables available to the install and build commands, for example a token for a private package registry or a public URL that a frontend build embeds. Values are passed as Docker build secrets. They never appear in the image or in the build log, and a changed value rebuilds the image.

Runtime variables come from the resource's environment property, not from buildEnvironment.

packaging: new BuildpackImagePackaging({
  sourceDirectoryPath: './web',
  buildEnvironment: [{ name: 'VITE_API_URL', value: 'https://api.example.com' }]
}),

Railpack configuration

railpackConfig accepts the same object as a railpack.json file. Use it for build steps, caches or deploy settings that the properties above do not cover. In a command list, "..." stands for the detected commands, so the example below runs npx prisma generate after the detected build.

packaging: new BuildpackImagePackaging({
  sourceDirectoryPath: './api',
  railpackConfig: {
    steps: { build: { commands: ['...', 'npx prisma generate'] } }
  }
}),

How the image is built

  1. Stacktape runs railpack prepare locally. It reads the project files and produces a build plan: tool versions, install, build and start commands.
  2. Docker BuildKit builds the plan with a pinned Railpack frontend image.
  3. The image is pushed to a managed ECR repository.

The railpack binary is downloaded on first use, like other external tools Stacktape uses. It is pinned by version and checksum. The first planning run needs network access to resolve tool versions.

Docker must be running. Both linux/amd64 and linux/arm64 images are supported.

Railpack's build uses a BuildKit feature that Docker's own builder offers only with the containerd image store. That store is the default for new installs of Docker Engine 29 and Docker Desktop 4.34 and later. Older or upgraded installs and GitHub-hosted runners use the classic store. There, Stacktape builds through its own Docker Buildx builder, stacktape-builder, which runs in a container and needs the Buildx plugin. Its first build downloads the base images again. It keeps its own build cache, which docker buildx prune --builder stacktape-builder clears.

Caching

If the source files, the build plan and the build variables have not changed, Stacktape reuses the previous image and skips the build.

When something has changed, BuildKit caches the dependency install layers, so a code-only change does not reinstall dependencies. The remote registry cache works the same way as for dockerfile builds.

The .stacktape directory Stacktape writes in the project is never part of the image or of the change detection.

Image base and size

The runtime image is based on Debian (trixie) with the resolved tool versions installed by mise. Images are larger than the Alpine images of js-bundle and of Stacktape v3.

Python

A Python project that uses pip (requirements.txt) or uv (uv.lock) is built on the official python:<version>-slim image instead, with the Python version Railpack detected. The interpreter comes with the image, so nothing is installed with mise, and the same image is the runtime. A FastAPI app is about 50 MB compressed.

  • Dependencies are installed into /app/.venv with uv. A requirements.txt is installed with uv pip install, and the environment keeps pip, so pip and python -m pip work in build commands and at runtime. When buildEnvironment has PIP_ variables, such as PIP_INDEX_URL for a private index, pip installs the requirements instead, because uv does not read them.
  • The slim image has no compiler. When a dependency has no prebuilt wheel for the platform, or a uv project compiles its own extension, the build installs a C toolchain and common development headers (including libpq-dev) and runs the install again (with pip for a requirements.txt). The result is cached like any other dependency install.
  • uv is in the runtime image only when the start command runs uv or uvx, for example uv run --no-sync python main.py.
  • Poetry, PDM and Pipenv projects, projects with other tools in packages, projects with a .tool-versions or mise.toml file, and builds with a custom installCommand or railpackConfig steps are built the Railpack way, with mise.

Framework and platform notes

Django migrations

Railpack's default Django start command runs manage.py migrate before starting gunicorn. Stacktape removes the migrate step, because migrations belong in a deployment hook, not in every container start. To run migrations at start anyway, set startCommand, for example python manage.py migrate && gunicorn --bind 0.0.0.0:$PORT config.wsgi.

Dev mode

In dev mode (stacktape dev), a buildpack service is rebuilt when its source changes. The dependency layer comes from the cache, so rebuilds after code changes are faster than the first build. There is no bind-mount reload as with js-bundle: every change produces a new image and restarts the container.

Windows

Railpack does not support its Windows binary. On Windows, Stacktape runs the Railpack planner inside Docker instead.

Monorepos and files outside the source directory

Only the files in sourceDirectoryPath are sent to the build. A service cannot build from its own directory when it needs something above it: a sibling workspace package, a lockfile at the workspace root, or, in .NET, a shared Directory.Packages.props or a referenced project in another directory.

For npm, pnpm, Yarn and Bun workspaces, set sourceDirectoryPath to the workspace root and point buildCommand and startCommand at the service. For a .NET solution with several projects, use dockerfile packaging: the .NET detection expects one .csproj file in sourceDirectoryPath.

Java version

Java services are built and run with JDK 21 unless you choose another version. A Gradle build that pins a toolchain, for example languageVersion = 17, fails with a different JDK. Set the same version in packages, for example java: '17'.

Full control with a Dockerfile

When detection and overrides are not enough, write a Dockerfile and use dockerfile packaging. You choose the base image, the build stages and the entrypoint.

Buildpack for Containers FAQ

Do I need Railpack installed?

No. Stacktape downloads a pinned railpack binary on first use and verifies its checksum. You need Docker.

Why does my web service fail its health check?

A common cause is an app that listens on a fixed port. Web services must listen on $PORT. Set startCommand so the server binds to 0.0.0.0:$PORT.

How do I pass a secret to the build?

Use buildEnvironment. Its values are Docker build secrets and do not end up in the image or the build log. For runtime secrets, use the resource's secrets or environment property. See secrets.

Can I keep my railpack.json?

Yes. A railpack.json in sourceDirectoryPath is applied. If the Stacktape configuration also sets railpackConfig, the configuration takes precedence.

API reference

BuildpackCwImagePackagingProps
Click a property in the tree to see its description, default value, and full type.