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-bundlebundles it into a smaller Alpine image. - You need full control over the image. Use
dockerfilefor 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.
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(includingpackageManagerandengines),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.jsonandgleam.toml. - Version files:
.nvmrc,.node-version,.python-version,.tool-versions,mise.tomlandrust-toolchain.toml. Procfile: overrides the detected start command.railpack.json: applied on top of the detected build. TherailpackConfigproperty 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
| Language | Package managers and build tools | Frameworks with detected build and start commands |
|---|---|---|
| Node.js | npm, pnpm, yarn, bun | Next.js, Astro, SvelteKit, Remix, Nuxt, TanStack, Nx, Angular. Vite and Create React App single-page apps are served by Caddy. |
| Python | pip, uv, poetry, pdm, pipenv | Django, FastAPI, Flask |
| PHP | Composer | Laravel, served by FrankenPHP |
| Ruby | Bundler | Rails |
| Go | Go modules | |
| Rust | Cargo | |
| Java | Maven, Gradle | |
| .NET | dotnet | |
| Elixir | Mix | Phoenix |
| Deno, Gleam | ||
| Other | C/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.
| Property | Purpose |
|---|---|
sourceDirectoryPath | Directory to build, relative to the Stacktape configuration file. Default: . |
startCommand | Command that starts the app. Runs through bash -c in /app. |
buildCommand | Command that builds the app after dependencies are installed. |
installCommand | Command that installs dependencies. The default is the package manager's locked install, such as npm ci or uv sync --locked. |
packages | Tool versions installed by mise, such as { node: '22', pnpm: '10' }. Use it when the project has no version file. |
aptPackages | Debian packages installed with apt, available during the build and at runtime. |
buildEnvironment | Environment variables for the install and build commands, passed as Docker build secrets. |
railpackConfig | A railpack.json configuration merged over the detected build. |
Start, build and install commands
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.
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.
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.
How the image is built
- Stacktape runs
railpack preparelocally. It reads the project files and produces a build plan: tool versions, install, build and start commands. - Docker BuildKit builds the plan with a pinned Railpack frontend image.
- 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/.venvwith uv. Arequirements.txtis installed withuv pip install, and the environment keeps pip, sopipandpython -m pipwork in build commands and at runtime. WhenbuildEnvironmenthasPIP_variables, such asPIP_INDEX_URLfor 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 arequirements.txt). The result is cached like any other dependency install. - uv is in the runtime image only when the start command runs
uvoruvx, for exampleuv run --no-sync python main.py. - Poetry, PDM and Pipenv projects, projects with other tools in
packages, projects with a.tool-versionsormise.tomlfile, and builds with a custominstallCommandorrailpackConfigsteps 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