Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.compartment.dev/llms.txt

Use this file to discover all available pages before exploring further.

The build block in a service config tells Compartment how to turn your source code into a runnable image. You can let Compartment choose automatically, force a specific strategy, provide a custom build command, install extra APT packages, and expose runtime variables at compile time. All build fields are optional — omitting the block entirely is equivalent to setting strategy: auto.

​
Fields

FieldTypeRequiredDefaultDescription
strategystringNoautoBuild strategy to use. One of auto, dockerfile, or railpack.
commandstringNo—Custom build command. Railpack strategy only.
envstring[]No[]Variable key names to expose during the build step.
packagesobjectNo—APT packages to install. Railpack strategy only.
packages.buildstring[]No[]APT packages installed in the build stage.
packages.runtimestring[]No[]APT packages installed in the runtime stage.

​
Build strategies

​
auto (default)

Compartment inspects your service directory and picks the right tool automatically:
  • If a Dockerfile is present → uses the Dockerfile build.
  • If no Dockerfile is present → uses Railpack to detect your framework and build automatically.
This is the recommended strategy for most projects. You do not need to set strategy at all when using auto detection. 
services:
  web:
    path: apps/web
    build:
      strategy: auto

​
dockerfile

Forces Compartment to use the Dockerfile in your service directory. The build fails if no Dockerfile is present. 
services:
  web:
    path: apps/web
    build:
      strategy: dockerfile
command and packages are not supported when using the dockerfile strategy. Define your build steps inside the Dockerfile itself. run.command is also not supported for Dockerfile-built services — set your start command via CMD or ENTRYPOINT in the Dockerfile.

​
railpack

Forces Compartment to use Railpack regardless of whether a Dockerfile exists. Use this when you want to opt into Railpack’s zero-config builds but your repository happens to contain a Dockerfile for a different purpose. 
services:
  web:
    path: apps/web
    build:
      strategy: railpack

​
Custom build command

Use command to override the build command that Railpack runs. This replaces whatever Railpack would infer from your project’s framework and package manager. 
services:
  web:
    path: apps/web
    build:
      strategy: railpack
      command: pnpm build
command is only valid for Railpack builds. Setting it alongside strategy: dockerfile is a validation error.

​
Exposing variables during the build

List variable key names under env to make those variables available to the build process. The values must already be set via compartment variable set or imported before you deploy. 
services:
  web:
    path: apps/web
    build:
      env:
        - VITE_PUBLIC_API_URL
        - NEXT_PUBLIC_STRIPE_KEY
Only the variables you list here are injected into the build environment. All other variables remain runtime-only and are not visible during the build step.

​
APT packages

Use packages to install additional APT packages that your build or runtime image needs. This is useful when a native dependency is not bundled by default in the Railpack base images. 
services:
  web:
    path: apps/web
    build:
      packages:
        build:
          - build-essential
        runtime:
          - libnss3
  • packages.build — packages installed during the build stage only. They are not present in the final runtime image.
  • packages.runtime — packages installed in the runtime stage. They are available when your service runs.
Package names follow the APT naming convention: they must start with a letter or digit and may contain letters, digits, and the characters ., +, :, =, ~, and -. If you specify packages, at least one of build or runtime must contain at least one entry.
packages is only valid for Railpack builds. Setting it alongside strategy: dockerfile is a validation error. Install additional packages in your Dockerfile’s RUN instructions instead.

​
Complete example

services:
  web:
    path: apps/web
    build:
      strategy: railpack
      command: pnpm build
      env:
        - VITE_PUBLIC_API_URL
      packages:
        build:
          - build-essential
        runtime:
          - libnss3

​
Strategy comparison

services:
  web:
    path: .
# No build block needed — auto is the default
Compartment detects the right tool. No configuration required.