Jets uses Docker to build and deploy your application by default. This page covers how it works and how to customize the Docker build process.

The Jets remote runner calls docker build and pushes the Docker image to ECR. Jets generates a Dockerfile, which is managed by the Jets remote build process. The generated Dockerfile can be customized for your purposes. This page covers Docker customization options.

  1. Jets Managed Dockerfile: Jets auto-detects the framework and builds and manages Dockerfile for you. IE: You don’t have to.
  2. Custom Dockerfile: You can use a custom Dockerfile. Jets will build using your Dockerfile.
  3. Prebuilt Docker Image: When there’s a config.docker.image config set. Jets uses your provided prebuilt Docker image.

Option #1, Jets Managed Dockerfile, is recommended. It’s powerful, flexible, and customizable, with a plethora of options to customize the generated Dockerfile.

Options #2 and #3 require more effort and work on your part because you need to manage the Dockerfile and are responsible for updating it entirely. You must make sure the Docker image is Lambda compatible. IE: It has the Lambda Runtime Interface Client installed as an entrypoint, a Lambda handler, any required dependencies, and patches.

Jets Managed Dockerfile

The Jets Docker build process adds conveniences such as auto-detecting your web framework, building a managed Dockerfile, auto-tagging the image, and making sure the image is Lambda compatible.

See: Jets Managed Dockerfile

Custom Dockerfile

To use a custom Dockerfile and let Jets build it. You can activate it.

Jets.deploy.configure do
  config.dockerfile.custom = true

Jets will attempt to build the Docker image using your custom Dockerfile. You will have to mimic what Jets does with the Jets Managed Dockerfile. Jets scripts will get updated over time, and you must keep them up-to-date. Using your own Dockerfile is also less powerful than the Jets-generated Dockerfile because Jets cannot inject dynamic logic, such as installing system packages based on gem auto-detection.

Note: You can also provide a String as a path config.dockerfile.custom = "dockerfiles/Dockerfile1"

Prebuilt Docker Image

You can also use a prebuilt Docker image. This can be useful if you already have your own CI build process and want to use the Docker image it produces. You use JETS_DOCKER_IMAGE. Example:

JETS_DOCKER_IMAGE=my/image:v1 jets deploy

The Docker build process will be skipped. Jets will push the image to ECR, though. Lambda has faster access to this image because it’s within the AWS network.


The table below covers each setting. Each option is configured with config.OPTION. The config. portion is not shown for conciseness. IE: logger.level vs config.logger.level.

Name Default Description
docker.image nil Prebuilt Docker Image.
docker.tag “:FRIENDLY_TAG-:TIMESTAMP-:GIT_SHA” Docker tag format string.
docker.show_build_command false Show docker build command in the deploy output.
dockerfile.add_deploy_user true Add deploy user and Docker USER deploy:deploy instruction to near the bottom of the Dockerfile. Turning this off will mean the USER will be root. Can be useful for debugging.
dockerfile.build_args.at_top nil Hash of vars you want Jets to use for docker build --build-arg. Added to the top of the Dockerfile.
dockerfile.build_args.build_stage nil Hash of vars you want Jets to use for docker build --build-arg. Added to the build stage of the Dockerfile.
dockerfile.build_args.deployment_stage nil Hash of vars you want Jets to use for docker build --build-arg. Added to the deployment stage of the Dockerfile.
dockerfile.build_args.enable_aws_creds true Enable auto-generated build-args that pass the CodeBuild IAM role to docker build. This allows the commands within the docker build process to have the same AWS access level as the CodeBuild remote runner.
dockerfile.commands.bootsnap nil For Rails, bundle exec bootsnap precompile app/ lib/. For other frameworks, nil.
dockerfile.custom false Allows you to use your own custom Dockerfile. Note, the Dockefile must be compatiable with Jets and Lambda. You are responsible for maintaining and updating it.
dockerfile.gemfile.force_ruby_platform false Adds a RUN bundle config set force_ruby_platform true before the bundle install in the Gemfile. Sometimes this helps fix some gem issues. This makes bundle install much slower. IE: 90s vs 20s.
dockerfile.install.awscli true Install the AWS CLI within the docker build.
dockerfile.apt.packages.all_stages [] Additional apt packages to install for all Docker stages.
dockerfile.apt.packages.build_stage [] Additional apt packages to install during the build Docker stage.
dockerfile.apt.packages.deployment_stage [] Additional apt packages to install during the deployment Docker stage.
dockerfile.auto_packages true Jets auto-detects required packages based on gems and automatically adds them.
dockerfile.copy_for_bundle nil List of folders to copy before the first bundle install. String or Array of Strings. This can be useful for copying files that are needed for the bundle install. IE: An engines folder with a Gemfile using path: engines/engine_name.
dockerfile.image_package.from_base.docker_image nil Full image name, IE: ruby:3.2.3-slim Overrides other settings.
dockerfile.image_package.from_base.image_name “ruby” Base image name without tag.
dockerfile.image_package.from_base.image_tag nil Auto-detected by default. IE: 3.2.3
dockerfile.image_package.from_base.image_variant “slim” Image variant.
dockerfile.image_package.from_base.ruby_version nil Auto-detected by default. IE: 3.2.3
dockerfile.yum.packages.all_stages [] Additional yum packages to install for all Docker stages.
dockerfile.yum.packages.build_stage [] Additional yum packages to install during the build Docker stage.
dockerfile.yum.packages.deployment_stage [] Additional yum packages to install during the deployment Docker stage
dockerfile.zip_package.from_base.docker_image nil Full image name, IE: Overrides other settings.
dockerfile.zip_package.from_base.image_name “” Base image name without tag.
dockerfile.zip_package.from_base.image_tag nil Auto-detected by default. IE: 3.2.3
dockerfile.zip_package.from_base.image_variant nil IE: “slim”. The AWS Lambda Image do not use variants.
dockerfile.zip_package.from_base.ruby_version nil Auto-detected by default. IE: 3.2.3

See Full Config Reference