Build an application with buildpacks

This guide shows you how to use buildpacks with your application source code to create a container image. For example, use buildpacks to build the source code of your Cloud Run service into a container image.

There are two methods for building container images with buildpacks:

• Build locally with the pack CLI to locally test your application and rapidly prototype changes before deployment.
• Build remotely with Cloud Build. Building with Cloud Build is useful for large applications that have a resource-intensive build processes and can also help protect your software supply chain.

Local builds

You use the pack CLI to locally build your application into a container image.

Before you begin

1. Install Docker Community Edition (CE) on your workstation. Docker is used by pack as an OCI image builder.
2. Install Pack CLI.
3. Install the Git source control tool to fetch the sample application from GitHub.

Build an application locally

You use the pack build command and specify the default builder --builder=gcr.io/buildpacks/builder to build your container images locally.

pack build --builder=gcr.io/buildpacks/builder IMAGE_NAME 

Replace IMAGE_NAME with the name of your service's container image.

You can also customize your container image by extending the build and run images.

Build a sample application locally

The following examples demonstrate how to build a sample locally.

1. Clone the sample repository to your local machine:

   git clone https://github.com/GoogleCloudPlatform/buildpack-samples.git

2. Change to the directory that contains the application sample code:

   Go

   cd buildpack-samples/sample-go

   Java

   cd buildpack-samples/sample-java-gradle

   Node.js

   cd buildpack-samples/sample-node

   PHP

   cd buildpack-samples/sample-php

   Python

   cd buildpack-samples/sample-python

   Ruby

   cd buildpack-samples/sample-ruby

   .NET

   cd buildpack-samples/sample-dotnet

3. Use pack to build the sample application image:

   Go

   pack build --builder=gcr.io/buildpacks/builder sample-go

   Java

   pack build --builder=gcr.io/buildpacks/builder sample-java-gradle

   Node.js

   pack build --builder=gcr.io/buildpacks/builder sample-node

   PHP

   pack build --builder=gcr.io/buildpacks/builder sample-php

   Python

   pack build --builder=gcr.io/buildpacks/builder sample-python

   Ruby

   pack build --builder=gcr.io/buildpacks/builder sample-ruby

   .NET

   pack build --builder=gcr.io/buildpacks/builder sample-dotnet

4. Run the image using docker:

   Go

   docker run -p8080:8080 sample-go

   Java

   docker run -it -ePORT=8080 -p8080:8080 sample-java-gradle

   Node.js

   docker run -it -ePORT=8080 -p8080:8080 sample-node

   PHP

   docker run -it --rm -p 8080:8080 sample-php

   Python

   docker run -it -ePORT=8080 -p8080:8080 sample-python

   Ruby

   docker run -it -ePORT=8080 -p8080:8080 sample-ruby

   .NET

   docker run -it -ePORT=8080 -p8080:8080 sample-dotnet

5. Visit the running application by browsing to localhost:8080.

Remote builds

Use Cloud Build to build your application into a container image and Artifact Registry as the container repository from where you store and deploy each image.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build and Artifact Registry APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build and Artifact Registry APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

1. Ensure that your Google Cloud project has access to a container image repository.

   To configure access to a Docker repository in Artifact Registry:

   1. Create a new Docker repository in the same location of your Google Cloud project.

      gcloud artifacts repositories create REPO_NAME \ --repository-format=docker \ --location=REGION --description="DESCRIPTION"

      Replace:
      • REPO_NAME with the name that you choose for your Docker repository.
      • REGION with the location in or nearest to the location of your Google Cloud project.
      • DESCRIPTION with a description of your choice.

      For example, to create a docker repository in us-west2 with the description "Docker repository", you run:

      gcloud artifacts repositories create buildpacks-docker-repo --repository-format=docker \ --location=us-west2 --description="Docker repository"

   2. Verify that your repository was created:

      gcloud artifacts repositories list

      You should see name that you choose for your Docker repository in the list.

Build an application remotely

You use the gcloud builds submit command to build and upload your container image to your repository.

You can choose to specify your container image in the command itself or use a configuration file.

Build with command

To build without a configuration file, you specify the image flag:

gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME

Replace:

• LOCATION with the region name of your container repository. Example: us-west2
• PROJECT_ID with the ID of your Google Cloud project.
• REPO_NAME with the name of your Docker repository.
• IMAGE_NAME with the name of your container image.

Example:

gcloud builds submit --pack image=us-west2-docker.pkg.dev/my-project-id/my-buildpacks-docker-repo/app-image

Build with configuration files

You can use a configuration file to define your image repository configuration details to simply the build command. The configuration file uses the YAML file format and must include a build step that uses the pack CLI.

1. Create a YAML file name cloudbuild.yaml that includes the URI of your container image repository.

 options:  logging: CLOUD_LOGGING_ONLY  pool: {}  projectId: PROJECT_ID  steps:  - name: gcr.io/k8s-skaffold/pack  entrypoint: pack  args:  - build  - LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME  - --builder  - gcr.io/buildpacks/builder:latest  - --network  - cloudbuild  images:  - LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME

Replace:

• LOCATION with the region name of your container repository, for example, us-west2.
• PROJECT_ID with the ID of your Google Cloud project.
• REPO_NAME with the name of your Docker repository.
• IMAGE_NAME with the name of your container image.

1. Build the application.

   If you named your configuration file cloudbuild.yaml, you can run the following command:

   gcloud builds submit . 

Example: Build a sample application remotely

The following examples demonstrate how to build a sample remotely and then verify that the container image was pushed to your repository in Artifact Registry.

1. Clone the sample repository to your local machine:

   git clone https://github.com/GoogleCloudPlatform/buildpack-samples.git

2. Change to the directory that contains the application sample code:

   Go

   cd buildpack-samples/sample-go

   Java

   cd buildpack-samples/sample-java-gradle

   Node.js

   cd buildpack-samples/sample-node

   PHP

   cd buildpack-samples/sample-php

   Python

   cd buildpack-samples/sample-python

   Ruby

   cd buildpack-samples/sample-ruby

   .NET

   cd buildpack-samples/sample-dotnet

3. Use gcloud to submit the application source code to Cloud Build:

   Go

   gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-go

   Java

   gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-java-gradle

   Node.js

   gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-node

   PHP

   gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-php

   Python

   gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-python

   Ruby

   gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-ruby

   .NET

   gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/sample-dotnet

4. Verify that the sample application was successfully published to REPO_NAME:

   gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME

   Replace:

   • LOCATION with the region name of your container repository. Example: us-west2
   • PROJECT_ID with the ID of your Google Cloud project.
   • REPO_NAME with the name of your Docker repository.

What's Next

• Deploy your image into Cloud Run.
• Set environment variables.
• Configure build images.
• Speed up builds with cache images.