# Build and push a Docker image with Cloud Build

Learn how to get started with Cloud Build by building a Docker image
and pushing the image to Artifact Registry. Artifact Registry provides a single
location for managing private packages and Docker container images.

You will first build the image using a `Dockerfile`, which is the Docker
configuration file, and then build the same image using the
Cloud Build configuration file.

> [!NOTE]
> **Note:** This quickstart shows you how to build an image with Docker, but Cloud Build supports most build tools and programming languages.

*** ** * ** ***

To follow step-by-step guidance for this task directly in the
Cloud Shell Editor, click **Guide me**:

[Guide me](https://console.cloud.google.com/getting-started?walkthrough_tutorial_id=cloud_build_quickstart)

*** ** * ** ***

## Before you begin

> [!NOTE]
> If you've already installed Google Cloud CLI previously, make sure you have the
> latest available version by running `gcloud components update`.

## Required roles


To get the permissions that
you need to build a Docker image and push it to Artifact Registry,

ask your administrator to grant you the
following IAM roles on the Cloud Build service account:

- [Artifact Registry Administrator](https://docs.cloud.google.com/iam/docs/roles-permissions/artifactregistry#artifactregistry.admin) (`roles/artifactregistry.admin`)
- [Cloud Build Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudbuild#cloudbuild.builds.editor) (`roles/cloudbuild.builds.editor`)
- [Logs Writer](https://docs.cloud.google.com/iam/docs/roles-permissions/logging#logging.logWriter) (`roles/logging.logWriter`)
- [Storage Bucket Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/storage#storage.bucketViewer) (`roles/storage.bucketViewer`)
- [Storage Object User](https://docs.cloud.google.com/iam/docs/roles-permissions/storage#storage.objectUser) (`roles/storage.objectUser`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Prepare source files to build

You'll need some sample source code to package into a container image. In this section,
you'll create a shell script and a `Dockerfile`. A `Dockerfile` is a text
document that contains instructions for Docker to build an image.

1. Open a terminal window.

2. Create a new directory named `quickstart-docker` and navigate into it:

       mkdir quickstart-docker
       cd quickstart-docker

3. Create a file named `quickstart.sh` with the following contents:

       #!/bin/sh
       echo "Hello, world! The time is $(date)."

4. Create a file named `Dockerfile` with the following contents:

       FROM alpine
       COPY quickstart.sh /
       CMD ["/quickstart.sh"]

5. In the terminal window, run the following command to make `quickstart.sh` executable:

       chmod +x quickstart.sh

## Create a Docker repository in Artifact Registry

1. Use the
   [`gcloud artifacts repositories create`](https://docs.cloud.google.com/sdk/gcloud/reference/artifacts/repositories/create)
   command to create a Docker repository named `quickstart-docker-repo` in the
   location `us-west2` with the description "Docker repository":

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

2. Verify that your repository was created:

       gcloud artifacts repositories list

   The list of displayed repositories should include `quickstart-docker-repo`.

   Artifact Registry uses a
   [naming convention](https://docs.cloud.google.com/artifact-registry/docs/docker/names) to identify
   repositories and images. For example, when you interact with Docker images
   stored in Artifact Registry in the `us-west2` region, you use
   `us-west2-docker.pkg.dev` as the registry hostname in your commands.

## Build an image using a Dockerfile

Use the [`gcloud builds submit`](https://docs.cloud.google.com/sdk/gcloud/reference/builds/submit) command to
build a Docker image using a `Dockerfile`. You don't require a separate
Cloud Build config file.

1. Get your Google Cloud project ID by running the following command:

       gcloud config get-value project

2. Run the following command from the directory containing `quickstart.sh` and
   `Dockerfile`:

       gcloud builds submit --region=us-west2 --tag us-west2-docker.pkg.dev/PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1

   > [!NOTE]
   > **Note:** If your project ID contains a colon, replace the colon with a forward slash.

   After the build is complete, the output should be similar to the following:

       DONE
       ---
       ID                                    CREATE_TIME                DURATION  SOURCE   IMAGES     STATUS
       545cb89c-f7a4-4652-8f63-579ac974be2e  2020-11-05T18:16:04+00:00  16S       gs://gcb-docs-project_cloudbuild/source/1604600163.528729-b70741b0f2d0449d8635aa22893258fe.tgz  us-west2-docker.pkg.dev/gcb-docs-project/quickstart-docker-repo/quickstart-image:tag1  SUCCESS

You've just built a Docker image named `quickstart-image` using a `Dockerfile`
and pushed the image to Artifact Registry.

## Build an image using a build config file

In this section you use a Cloud Build config file to build the same
Docker image built in the previous steps. The build config file instructs
Cloud Build to perform tasks based on your specifications.

1. In the same directory that contains `quickstart.sh` and the `Dockerfile`,
   create a file named `cloudbuild.yaml` with the following contents. This file is
   your build config file. At build time, Cloud Build automatically
   replaces `$PROJECT_ID` with your project ID.

       steps:
       - name: 'gcr.io/cloud-builders/docker'
         script: |
           docker build -t us-west2-docker.pkg.dev/$PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1 .
         automapSubstitutions: true
       images:
       - 'us-west2-docker.pkg.dev/$PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1'

2. Start the build by running the following command:

       gcloud builds submit --region=us-west2 --config cloudbuild.yaml

   After the build is complete, the output should be similar to the following:

        DONE
        ---
        ID                                    CREATE_TIME                DURATION  SOURCE          IMAGES          STATUS
        046ddd31-3670-4771-9336-8919e7098b11  2020-11-05T18:24:02+00:00  15S       gs://gcb-docs-project_cloudbuild/source/1604600641.576884-8153be22c94d438aa86c78abf11403eb.tgz  us-west2-docker.pkg.dev/gcb-docs-project/quickstart-docker-repo/quickstart-image:tag1  SUCCESS

You've just built `quickstart-image` using the build config file and pushed the
image to Artifact Registry.

## View build details

1. Open the Cloud Build page in the Google Cloud console.

   [Open the Cloud Build page](https://console.cloud.google.com/cloud-build)
2. If necessary, select your project and click **Open**.

   You will see the **Build history** page:

   ![Screenshot of the build history page](https://docs.cloud.google.com/build/images/docker-build-history.png)
3. If necessary, select `us-west2`in the **Region** drop-down menu to view
   builds in that region.

   There will be two builds listed, one for each of the builds you executed in
   this quickstart.
4. Click one of the builds.

   You will see the **Build details** page.
5. To view the artifacts of your build, under **Build Summary** , click **Build artifacts**.

   You should see output similar to the following:

   ![Screenshot of build artifacts](https://docs.cloud.google.com/build/images/docker-artifacts.png)

   You can download your build log and view your image details in
   Artifact Registry from this page.

## Clean up


To avoid incurring charges to your Google Cloud account for
the resources used on this page, follow these steps.

1. Open the Artifact Registry page in the Google Cloud console.

   [Open the Artifact Registry page](https://console.cloud.google.com/artifacts)
2. Select your project and click **Open**.

3. Select **quickstart-docker-repo**.

4. Click **Delete**.

You have now deleted the repository that you created as part of this quickstart.

## What's next

- Learn how to [run a Docker image](https://docs.cloud.google.com/build/docs/building/build-containers#run_the_docker_image).
- Learn how to [create a basic build config
  file](https://docs.cloud.google.com/build/docs/configuring-builds/create-basic-configuration).
- Learn how to [deploy using Cloud Build](https://docs.cloud.google.com/build/docs/deploy-containerized-application-cloud-run).
- Learn how to [build Node.js applications](https://docs.cloud.google.com/build/docs/building/build-nodejs).
- Learn how to [build Java applications](https://docs.cloud.google.com/build/docs/building/build-java).
- Learn how to [build Go applications](https://docs.cloud.google.com/build/docs/building/build-go).