Custom build images and live package updates - AWS Amplify Hosting
Custom build imagesLive package updates

Custom build images and live package updates

Custom build images

You can use a custom build image to provide a customized build environment for an Amplify app. If you have specific dependencies that take a long time to install during a build using Amplify's default container, you can create your own Docker image and reference it during a build. Images can be hosted on Amazon Elastic Container Registry Public.

Note

Build settings is visible in the Amplify console’s App settings menu only when an app is set up for continuous deployment and connected to a git repository. For instructions on this type of deployment, see Getting started with existing code.

Custom build image requirements

For a custom build image to work as an Amplify build image, it must meet the following requirements:

  1. A Linux distribution that supports the GNU C Library (glibc), such as Amazon Linux, compiled for the x86-64 architecture.

  2. cURL: When we launch your custom image, we download our build runner into your container, and therefore we require cURL to be present. If this dependency is missing, the build instantly fails without any output as our build-runner is unable to produce any output.

  3. Git: In order to clone your Git repository we require Git to be installed in the image. If this dependency is missing, the Cloning repository step will fail.

  4. OpenSSH: In order to securely clone your repository we require OpenSSH to set up the SSH key temporarily during the build. The OpenSSH package provides the commands that the build runner requires to do this.

  5. Bash and The Bourne Shell: These two utilities are used to run commands at build time. If they aren't installed, your builds might fail prior to starting.

  6. Node.JS+NPM: Our build runner doesn't install Node. Instead, it relies on Node and NPM being installed in the image. This is only required for builds that require NPM packages or Node specific commands. However, we strongly recommend installing them because when they are present, the Amplify build runner can use these tools to improve the build execution. Amplify's package override feature uses NPM to install the Hugo-extended package when you set an override for Hugo.

The following packages aren't required, but we strongly recommend that you install them.

  1. NVM (Node Version Manager): We recommend that you install this version manager if you need to handle different versions of Node. When you set an override, Amplify’s package override feature uses NVM to change Node.js versions before each build.

  2. Wget: Amplify can use the Wget utility to download files during the build process. We recommend that you install it in your custom image.

  3. Tar: Amplify can use the Tar utility to uncompress downloaded files during the build process. We recommend that you install it in your custom image.

Configuring a custom build image

To configure a custom build image hosted in Amazon ECR

  1. See Getting started in the Amazon ECR Public User guide to set up an Amazon ECR Public repository with a Docker image.

  2. Sign in to the AWS Management Console and open the Amplify console.

  3. Choose the app that you want to configure a custom build image for.

  4. In the navigation pane, choose App Settings, Build settings.

  5. On the Build settings page, in the Build image settings section, choose Edit.

  6. In the Edit build image settings dialog box, expand the Build image menu, and choose Build image.

  7. Enter the name of the Amazon ECR Public repo that you created in step one. This is where your build image is hosted. For example, if the name of your repo is ecr-examplerepo, you would enter public.ecr.aws/xxxxxxxx/ecr-examplerepo.

  8. Choose Save.

Live package updates

Live package updates enable you to specify versions of packages and dependencies to use in the Amplify default build image. The default build image comes with several packages and dependencies pre-installed (e.g. Hugo, Amplify CLI, Yarn, etc). With live package updates you can override the version of these dependencies and specify either a specific version, or ensure that the latest version is always installed.

If live package updates is enabled, before your build runs, the build runner first updates (or downgrades) the specified dependencies. This increases the build time proportional to the time it takes to update the dependencies, but the benefit is that you can ensure the same version of a dependency is used to build your app.

Warning

Setting the Node.js version to latest causes builds to fail. Instead, you must specify an exact Node.js version, such as 18, 21.5, or v0.1.2.

Configuring live package updates

To configure live package updates

  1. Sign in to the AWS Management Console and open the Amplify console.

  2. Choose the app that you want to configure live package updates for.

  3. In the navigation pane, choose App Settings, Build settings.

  4. On the Build settings page, in the Build image settings section, choose Edit.

  5. In the Edit build image settings dialog box, expand the Add package version override list, and choose the package you want to change.

    The following screenshot shows the Edit build image settings dialog box with the expanded Add package version override list.

    The Edit build image settings dialog box in the Amplify console with the Add package override list expanded.

  6. For Version, either keep the default latest or enter a specific version of the dependency. If you use latest, the dependency will always be upgraded to the latest version available.

  7. Choose Save.