Build application artifacts with modules

Modules with the build capability know how to build their own code. The module’s definition carries the full build config — source repo, builder, and artifact destinations — so you build it from a pipeline with a one-line build step instead of copying that config into every pipeline. Depending on the module, a build produces a container image (pushed to ECR), a directory of static assets (uploaded to S3), or a Lambda zip package (uploaded to S3).

Builds only run through pipelines. There is no standalone build command or dashboard button. You either add a build step to a Ravion pipeline, or build in an external CI system and hand Ravion the finished artifact at deploy time.

Build config is part of the module config

You configure a module’s build the same way you configure everything else about it: through the module instance’s inputs, alongside its runtime config. There is no separate build file. For example, the web-app module in a project config file sets its build inputs next to its port and health check:

- givenId: web-app
  type: rvn-ecs-web
  version: 2.2.0
  input:
    # build config
    build_source: dockerfile
    source_repo: my-org/my-repo
    dockerfile: Dockerfile
    # runtime config
    container_port: 80
    health_check_path: /

Running a build

Add a build step to your pipeline and point it at the module instance:

- id: build_web_app
  type: build
  module_instance: << pipeline.variant.id >>.web-app
  input:
    image_tag: << pipeline.input.commit >>

module_instance accepts a unique ID (mi_…), environment.module, or project.environment.module.
input passes build-time values the module accepts, such as a tag, branch, or commit. Check the module’s docs or schema (ravion module schema <module-type>) for what it takes.

Builds run in your AWS account, so your source code never enters the Ravion control plane. Sandbox builds keep Docker layer cache on disk between successful runs.

Building something that isn’t a module? Use the standalone build:image or build:static CI steps, which take the full build config inline.

Build infrastructure

New instances of the latest standard library modules default to Sandbox builds: Firecracker microVMs with 14 vCPUs, 28 GiB memory and 30 GiB disk. The first build creates the host pool automatically. You don’t need to choose EC2 machine types. Before your first sandbox build, update your AWS permissions. Use sandboxes unless your build needs a custom AMI or direct access to a dedicated EC2 instance. For those requirements, change Builder capacity type to EC2 or EC2 spot. The build uses the module’s Terraform execution environment unless you set Builder execution environment. In Builder config, you can adjust Builder vCPUs, Builder memory (GiB) and Builder disk (GiB). Existing module instances keep their saved builder settings when upgraded. To move an existing EC2 build to a sandbox, open Builder config, set Builder capacity type to Sandbox, and choose its CPU and memory. Older module versions may still label this option Sandbox (preview). Sandbox builds use disk_cache: auto to keep dependencies, build output and Docker layers between successful runs. Interruptible build is on by default, allowing spot hosts and a restart from the beginning if the host is lost. Turn it off if your build changes external state, such as running database migrations. See Sandboxes for pool settings, disk cache and cold-start behavior.

Docker layer cache

Sandbox module builds keep Docker’s build cache on the sandbox disk. With disk_cache: auto, Ravion saves the disk after a successful run and restores it for later runs. Dependencies, build output and Docker layers remain available without configuring a separate cache. See Disk cache for branch restore rules. Disk caching also benefits static asset and Lambda builds. To get the most out of the cache:

Order your Dockerfile from least- to most-frequently-changed. Copy manifest files (package.json, go.mod, requirements.txt) and install dependencies before copying the rest of the source. That way a source change doesn’t invalidate the dependency layer.
Pin base images by digest (or a specific tag) so the base layer is stable across builds.

build:image builds also use layer cache from ECR, alongside the local disk cache. Ravion imports cache from an image in the destination repository and its dedicated buildcache tag. This can help when a saved disk has no matching layers. On sandboxes, Ravion exports registry cache when a build pushes a new image digest, rather than on every unchanged build.

Choosing the cache source yourself

You don’t need to choose a registry cache source for sandbox disk caching. For image builds that import ECR cache, module definitions select that source for you. To choose it yourself, use a standalone build:image step and set cache_from on its builder block: This example uses ci-builders as an execution environment given ID; replace it with yours.

- id: build_image
  type: build:image
  source:
    type: git
    repo: https://github.com/my-org/my-repo
    branch: << pipeline.input.branch >>
  builder:
    type: dockerfile
    dockerfile: Dockerfile
    cache_from:
      tag: release    # or: digest: sha256:...
  destinations:
    - id: ecr
      type: ecr
      repository_arn: arn:aws:ecr:us-east-1:123456789012:repository/my-app
  infrastructure:
    type: sandbox
    cpu: 2
    memory: 4
    disk: 30
    disk_cache: auto
    execution_environment_id: ci-builders

Both tag and digest are optional, accept template tokens, and resolve against the step’s first ECR destination — so the tag or digest you name has to exist in that repo. digest wins if you set both. Omit cache_from entirely and the step falls back to the most recent image in that repo. See CacheFromConfig for the full field list.

Inspecting builds

A build is a pipeline step execution — there’s no separate build entity or command. Find it in the pipeline run:

# Stream the run until it finishes, then read the step logs
ravion pipeline run wait <pipeline-run-id> --watch --timeout 30m
ravion logs pipeline-step <step-execution-id>

Feeding the artifact to a deploy

Every build step outputs build_ref — the canonical reference to the artifact it produced:

Build kind	`build_ref` value
Image	Digest-pinned image URI
Static	S3 directory containing the assets
Lambda	S3 key of the uploaded zip

Pass it to the deploy step:

- id: deploy_web_app
  type: deploy
  module_instance: << pipeline.variant.id >>.web-app
  input:
    image_ref: << steps.build_web_app.output.build_ref >>

This is the whole build-to-deploy contract: the build step produces a pinned artifact reference, and the deploy step releases exactly that artifact. Type-specific outputs are also available when you need them — image_uri, image_digest, s3_bucket, s3_directory, s3_key, and more.

Building outside Ravion

You don’t have to build in Ravion at all. Module definitions typically include a prebuilt image or package option for teams that build in GitHub Actions, CircleCI, or another external system. For example, rvn-ecs-web supports these build_source values:

Build source	What you configure on the module	What the deploy takes as `image_ref`
`dockerfile` / `railpack`	Git repo and build settings — Ravion builds and pushes to the module’s ECR repo	Digest from the build step
`image_registry`	The image repository (Docker Hub, GHCR, ECR, …) without a tag, plus registry credentials if private	The tag or digest to deploy

So with an external build, the flow is: your CI builds and pushes the image, then triggers the release with the artifact reference:

ravion deploy create --module-instance-id <mi-id> \
  --description "Release $GITHUB_SHA" \
  --inputs '{"image_ref": "'"$IMAGE_TAG"'"}'

Ravion still handles the rollout, deploy history, events, and rollback — it just doesn’t do the building.

For module authors

How a definition declares its build config — builders (dockerfile, railpack), destinations, build inputs, and templating — is covered in the module definition schema.

Introduction

Concepts

Config as code

Migrate

Modules

Pipelines

Guides

Troubleshooting

Agent setup

Module definitions

Build application artifacts with modules

Build config is part of the module config

Running a build

Build infrastructure

Docker layer cache

Choosing the cache source yourself

Inspecting builds

Feeding the artifact to a deploy

Building outside Ravion

For module authors

​Build config is part of the module config

​Running a build

​Build infrastructure

​Docker layer cache

​Choosing the cache source yourself

​Inspecting builds

​Feeding the artifact to a deploy

​Building outside Ravion

​For module authors

Build config is part of the module config

Running a build

Build infrastructure

Docker layer cache

Choosing the cache source yourself

Inspecting builds

Feeding the artifact to a deploy

Building outside Ravion

For module authors