App Runner service based on source code - AWS App Runner
Source code repository providersSource directoryApp Runner managed platformsManaged runtime versions and the App Runner build

App Runner service based on source code

You can use AWS App Runner to create and manage services based on two fundamentally different types of service source: source code and source image. Regardless of the source type, App Runner takes care of starting, running, scaling, and load balancing your service. You can use the CI/CD capability of App Runner to track changes to your source image or code. When App Runner discovers a change, it automatically builds (for source code) and deploys the new version to your App Runner service.

This chapter discusses services based on source code. For information about services based on a source image, see App Runner service based on a source image.

Source code is application code that App Runner builds and deploys for you. You point App Runner to a source directory in a code repository and choose a suitable runtime that corresponds to a programming platform version. App Runner builds an image that's based on the base image of the runtime and your application code. It then starts a service that runs a container based on this image.

App Runner provides convenient platform-specific managed runtimes. Each one of these runtimes builds a container image from your source code, and adds language runtime dependencies into your image. You don't need to provide container configuration and build instructions such as a Dockerfile.

Subtopics of this chapter discuss the various platforms that App Runner supports— managed platforms that provide managed runtimes for different programming environments and versions.

Topics

Source code repository providers

App Runner deploys your source code by reading it from a source code repository. App Runner supports two source code repository providers: GitHub and Bitbucket.

Deploying from your source code repository provider

To deploy your source code to an App Runner service from a source code repository, App Runner establishes a connection to it. When you use the App Runner console to create a service, you provide connection details and a source directory for App Runner to deploy your source code.

Connections

You provide connection details as part of the service creation procedure. When you use the App Runner API or the AWS CLI, a connection is a separate resource. First, you create the connection using the CreateConnection API action. Then, you provide the connection's ARN during service creation using the CreateService API action.

Source directory

When you create a service you also provide a source directory. By default, App Runner uses the root directory of your repository as the source directory. The source directory is the location in your source code repository that stores your application’s source code and configuration files. The build and start commands also execute from the source directory. When you use the App Runner API or the AWS CLI to create or update a service you provide the source directory in the CreateService and UpdateService API actions. For more information, see the Source directory section that follows.

For more information about App Runner service creation, see Creating an App Runner service. For more information about App Runner connections, see Managing App Runner connections.

Source directory

When you create an App Runner service you can provide the source directory, along with the repository and branch. Set the value of the Source directory field to the repository directory path that stores the application’s source code and configuration files. App Runner executes the build and start commands from the source directory path that you provide.

Enter the value for source directory path as absolute from the root repository directory. If you don’t specify a value, it defaults to the repository top-level directory, also known as the repository root directory.

You also have the option to provide different source directory paths besides the top-level repository directory. This supports a monorepo repository architecture, which means the source code for multiple applications is stored in one repository. To create and support multiple App Runner services from a single monorepo, specify different source directories when you create each service.

Note

If you specify the same source directory for multiple App Runner services, both services will deploy and operate individually.

If you opt to use an apprunner.yaml configuration file to define your service parameters place it in the source directory folder of the repository.

If the Deployment trigger option is set to the Automatic, the changes you commit in the source directory will trigger an automatic deployment. Only the changes in the source directory path will trigger an automatic deployment. It’s important to understand how the location of the source directory affects the scope of an automatic deployment. For more information, see automated deployments in Deployment methods.

Note

If your App Runner service uses the PHP managed runtimes, and you'd like to designate a source directory other than the default root repository, it's important to use the correct PHP runtime version. For more information, see Using the PHP platform.

App Runner managed platforms

App Runner managed platforms provide managed runtimes for various programming environments. Each managed runtime makes it easy to build and run containers based on a version of a programming language or runtime environment. When you use a managed runtime, App Runner starts with a managed runtime image. This image is based on the Amazon Linux Docker image and contains a language runtime package as well as some tools and popular dependency packages. App Runner uses this managed runtime image as a base image, and adds your application code to build a Docker image. It then deploys this image to run your web service in a container.

You specify a runtime for your App Runner service when you create a service using the App Runner console or the CreateService API operation. You can also specify a runtime as part of your source code. Use the runtime keyword in a App Runner configuration file that you include in your code repository. The naming convention of a managed runtime is <language-name><major-version>.

App Runner updates the runtime for your service to the latest version on every deployment or service update. If your application requires a specific version of a managed runtime, you can specify it using the runtime-version keyword in the App Runner configuration file. You can lock to any level of version, including a major or minor version. App Runner only makes lower-level updates to the runtime of your service.

Managed runtime versions and the App Runner build

App Runner now offers an updated build process for your applications. It currently invokes the new build for services that run on managed runtimes Python 3.11 and Node.js 18, last released on December 29, 2023. This revised build process is faster and more efficient. It also creates a final image with a smaller footprint that only contains your source code, build artifacts, and runtimes needed to run your application.

We refer to the newer build process as the revised App Runner build and to the original build process as the original App Runner build. To avoid breaking changes to earlier version of runtime platforms, App Runner only applies the revised build to specific runtime versions, typically newly released major releases.

We’ve introduced a new component to the apprunner.yaml configuration file to make the revised build backward compatible for a very specific use case and to also provide more flexibility to configure the build of your application. This is the optional pre-run parameter. We explain when to use this parameter along with other useful information about the builds in the sections that follow.

The following table conveys which version of the App Runner build applies to specific managed runtime versions. We'll continue to update this document to keep you informed about our current runtimes.

Platform Original build Revised build

Python – Release information

  • Python 3.8

  • Python 3.7

  • Python 3.11 (!)

Node.js – Release information

  • Node.js 16

  • Node.js 14

  • Node.js 12

  • Node.js 18

Corretto – Release information

  • Corretto 11

  • Corretto 8

.NET – Release information

  • .NET 6

PHP – Release information

  • PHP 8.1

Ruby – Release information

  • Ruby 3.1

Go – Release information

  • Go 1
Important

Python 3.11 – We have specific recommendations for the build configuration of services that use the Python 3.11 managed runtime. For more information, see Callouts for specific runtime versions in the Python platform topic.

More about the App Runner builds and migration

When you migrate your application to a newer runtime that uses the revised build, you may need to slightly modify your build configuration.

To provide context for migration considerations, we'll first describe the high level processes for both the original App Runner build and the revised build. We'll follow with a section that describes specific attributes about your service that might require some configuration updates.

The original App Runner build

The original App Runner application build process leverages the AWS CodeBuild service. The initial steps are based on images curated by the CodeBuild service. A Docker build process follows that uses the applicable App Runner managed runtime image as the base image.

The general steps are the following:

  1. Run pre-build commands in a CodeBuild-curated image.

    The pre-build commands are optional. They can only be specified in the apprunner.yaml configuration file.

  2. Run the build commands using CodeBuild on the same image from the prior step.

    The build commands are required. They can be specified in the App Runner console, the App Runner API, or in the apprunner.yaml configuration file.

  3. Run a Docker build to generate an image based on the App Runner managed runtime image for your specific platform and runtime version.

  4. Copy the /app directory from the image that we generated in Step 2. The destination is the image based on the App Runner managed runtime image, that we generated in Step 3.

  5. Run the build commands again on the generated App Runner managed runtime image. We run the build commands again to generate build artifacts from the source code in the /app directory that we copied to it in Step 4. This image will later be deployed by App Runner to run your web service in a container.

    The build commands are required. They can be specified in the App Runner console, the App Runner API, or in the apprunner.yaml configuration file.

  6. Run post-build commands in the CodeBuild image from Step 2.

    The post-build commands are optional. They can only be specified in the apprunner.yaml configuration file.

After the build completes, App Runner deploys the generated App Runner managed runtime image from Step 5 to run your web service in a container.

The revised App Runner build

The revised build process is faster and more efficient than the original build process described in the prior section. It eliminates the duplication of the build commands that occurs in the prior version build. It also creates a final image with a smaller footprint that only contains your source code, build artifacts, and runtimes needed to run your application.

This build process uses a Docker multi-stage build. The general process steps are the following:

  1. Build stage — Start a docker build process that executes pre-build and build commands on top of the App Runner build images.

    1. Copy the application source code to the /app directory.

      Note

      This /app directory is designated as the working directory in every stage of the Docker build.

    2. Run pre-build commands.

      Thepre-build commands are optional. They can only be specified in the apprunner.yaml configuration file.

    3. Run the build commands.

      The build commands are required. They can be specified in the App Runner console, the App Runner API, or in the apprunner.yaml configuration file.

  2. Packaging stage — Generates the final customer container image, which is also based on the App Runner run image.

    1. Copy the /app directory from the prior Build stage to the new Run image. This includes your application source code and the build artifacts from the prior stage.

    2. Run the pre-run commands. If you need to modify the runtime image outside of the /app directory by using the build commands, add the same or required commands to this segment of the apprunner.yaml configuration file.

      This is a new parameter that was introduced to support the revised App Runner build.

      The pre-run commands are optional. They can only be specified in the apprunner.yaml configuration file.

      Notes

      • The pre-run commands are only supported by the revised build. Do not add them to the configuration file if your service uses runtime versions that use the original build.

      • If you don't need to modify anything outside of the /app directory with the build commands, then you don’t need to specify pre-run commands.

  3. Post-build stage — This stage resumes from the Build stage and runs post-build commands.

    1. Run the post-build commands inside the /app directory.

      The post-build commands are optional. They can only be specified in the apprunner.yaml configuration file.

After the build completes, App Runner then deploys the Run image to run your web service in a container.

Note

Don’t be misled to the env entries in the Run section of the apprunner.yaml when configuring the build process. Even though the pre-run command parameter, referenced in Step 2(b), resides in the Run section, don't use the env parameter in the Run section to configure your build. The pre-run commands only reference the env variables defined in the Build section of the configuration file. For more information, see Run section in the App Runner configuration file chapter.

Service requirements for migration consideration

If your application environment has either of these two requirements, then you'll need to revise your build configuration, by adding pre-run commands.

  • If you need to modify anything outside of the /app directory with the build commands.

  • If you need to run the build commands twice to create the required environment. This is a very unusual requirement. The vast majority of builds will not do this.

Modifications outside the /app directory

  • The revised App Runner build assumes that your application does not have dependencies outside the /app directory.

  • The commands that you provide either with the apprunner.yaml file, the App Runner API, or the App Runner console must generate build artifacts in the /app directory.

  • You can modify the pre-build, build, and post-build commands to ensure all the build artifacts are in the /app directory.

  • If your application requires the build to further modify the generated image for your service, outside of the /app directory, you can use the new pre-run commands in the apprunner.yaml. For more information, see Setting App Runner service options using a configuration file.

Running the build commands twice

  • The original App Runner build runs the build commands twice, first in Step 2, then again in Step 5. The revised App Runner build remedies this redundancy and only runs the build commands one time. If your application should have an unusual requirement for the build commands to run twice, the revised App Runner build provides the option to specify and execute the same commands again using the pre-run parameter. Doing so retains the same double build behavior.