From 1eda348cde7bd0d78d5e406ba0c78003eb67aed0 Mon Sep 17 00:00:00 2001 From: Josh W Lewis Date: Thu, 30 May 2024 09:51:11 -0500 Subject: [PATCH] Update build.md directions (#310) --- BUILD.md | 61 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 34 insertions(+), 27 deletions(-) diff --git a/BUILD.md b/BUILD.md index 86cc02e0..9aedf6df 100644 --- a/BUILD.md +++ b/BUILD.md @@ -2,57 +2,64 @@ ## Prepare your local environment -The build scripts in this repository require bash 4+. To update to newer bash on OS X, see: -https://johndjameson.com/blog/updating-your-shell-with-homebrew/ +The build scripts in this repository require: -## Adding packages to the base image +- bash 4+. To update to newer bash on OS X, see: https://johndjameson.com/blog/updating-your-shell-with-homebrew/ +- Docker Desktop. To build multi-arch images (heroku-24 and beyond), + the `containerd` snapshotter feature should be enabled. -Add the package you want to the appropriate `setup.sh` for example `heroku-22/setup.sh`: +## Build -```diff -+ libc6-dev \ -``` +To build the base images locally, run this from the repo root: -Once done, run the `bin/build.sh` locally to generate the corresponding `installed-packages.txt`. + bin/build.sh STACK_VERSION -The `*-build` variants include all the packages from the non-build variant by default. This means that if you're adding a package to both, you only need to add them to the non-build variant. The example above will add `libc6-dev` to both `heroku-22` and `heroku-22-build`. +For example: -The `*cnb*` variants inherit the installed packages from the non-`*cnb*` variant. Add packages to a non-`*cnb*` variant to add them to the `*cnb*` variant. + ./bin/build.sh 24 -## Build +### Multi-architecture images (heroku-24 and later) -To build the base images locally, run this from the repo root: +This script will build a family of 2 images: - bin/build.sh STACK_VERSION +* `heroku/heroku:{STACK_VERSION}` - A multi-architecture manifest list of Heroku base runtime images supporting `amd64` and `arm64` architectures +* `heroku/heroku:{STACK_VERSION}-build` - A multi-architecture manifest list of Heroku base build images supporting `amd64` and `arm64` architectures -For example: +### Single architecture images (heroku-22 and prior) + +This script will build a family of 4 images: + +* `heroku/heroku:{STACK_VERSION}` - The Heroku base run image supporting `amd64` architecture +* `heroku/heroku:{STACK_VERSION}-build` - The Heroku base build image supporting `amd64` architecture +* `heroku/heroku:{STACK_VERSION}-cnb` - The Heroku base run image for Cloud Native Buildpacks supporting `amd64` architecture +* `heroku/heroku:{STACK_VERSION}-cnb-build` - The Heroku base build image for Cloud Native Buildpacks supporting `amd64` architecture - ./bin/build.sh 22 +## Adding packages to the base image + +Add the package you want to the appropriate `setup.sh` for example `heroku-24/setup.sh`: -If you're building on a machine with an architecture other than amd64, set `DOCKER_DEFAULT_PLATFORM` to the appropriate "`linux/amd64`" value in the environment: +```diff ++ libc6-dev +``` - DOCKER_DEFAULT_PLATFORM=linux/amd64 ./bin/build.sh 22 +Once done, run `bin/build.sh` locally to generate the corresponding `installed-packages*` files. Multi-arch base images (heroku-24 and beyond) will produce an `installed-packages-$ARCH.txt` for each architecture, while single architecture images will produce a singular `installed-packages.txt`. -The supported stacks are: `20` and `22`. This script will build a family -of 4 images: +The `*-build` variants include all the packages from the non-build variant by default. This means that if you're adding a package to both, you only need to add them to the non-build variant. The example above will add `libc6-dev` to both `heroku-24` and `heroku-24-build`. -* `heroku/heroku:{STACK_VERSION}` - The base run image for the Heroku platform -* `heroku/heroku:{STACK_VERSION}-build` - The base build image for the Heroku platform -* `heroku/heroku:{STACK_VERSION}-cnb` - The base run image for Cloud Native Buildpacks -* `heroku/heroku:{STACK_VERSION}-cnb-build` - The base build image for Cloud Native Buildpacks +The `*cnb*` variants (which only exist for heroku-22 and prior) inherit the installed packages from the non-`*cnb*` variant. Add packages to a non-`*cnb*` variant to add them to the `*cnb*` variant. # Releasing Heroku Base Images We use GitHub Actions to build and release Heroku Base Images: -* Any push to `main` will build the images and push the nightly Docker tag variants (such as `heroku/heroku:22-build.nightly`). -* Any new Git tag will build the image and push the latest Docker tag (such as `heroku/heroku:22-build`), - as well as a versioned tag (such as `heroku/heroku:22-build.v123`). The Docker image will then also be +* Any push to `main` will build the images and push the nightly Docker tag variants (such as `heroku/heroku:24-build.nightly`). +* Any new Git tag will build the image and push the latest Docker tag (such as `heroku/heroku:24-build`), + as well as a versioned tag (such as `heroku/heroku:24-build.v123`). The `arm64` images will then also be converted to a Heroku-specific `.img` format and uploaded to S3 for consumption by the runtime hosts. # Generating `.img` format Base Images locally -To test the generation of the Heroku-specific `.img` file: +To test the generation of the Heroku-specific, amd64-only `.img` file: 1. Build the Docker images for your chosen stack as normal above. 2. `docker build --platform=linux/amd64 ./tools -t heroku-image-tools`