Quickstart for Docker

Artifact Registry provides a single location for managing private packages and Docker container images.

This quickstart shows you how to:

  • Create a Docker repository in Artifact Registry
  • Set up authentication
  • Push an image to the repository
  • Pull the image from the repository

For step-by-step guidance on this task directly in Cloud Console, click Guide me:

Guide me


The following sections take you through the same steps as clicking Guide me.

Before you begin

  1. 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.
  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  4. Enable the Artifact Registry API.

    Enable the API

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

    Go to project selector

  6. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  7. Enable the Artifact Registry API.

    Enable the API

Choose a shell

To complete this quickstart, use either Cloud Shell or your local shell.

Cloud Shell
Cloud Shell is a shell environment for managing resources hosted on Google Cloud. It comes preinstalled with Docker and the gcloud command-line tool, the primary command-line interface for Google Cloud.
Local shell
If you prefer using your local shell, you must install Docker and Cloud SDK in your environment.

Starting Cloud Shell

To launch Cloud Shell, perform the following steps:

  1. Go to Google Cloud Console.

    Google Cloud Console

  2. Click the Activate Cloud Shell button: "".

A Cloud Shell session opens inside a frame lower on the console. You use this shell to run gcloud commands.

Setting up a local shell

To install Cloud SDK and Docker, perform the following steps:

  1. Install the Cloud SDK, which includes the gcloud command-line tool. To update an existing installation, run the command gcloud components update.

  2. Install Docker if it is not already installed.

  3. Docker requires privileged access to interact with registries. On Linux or Windows, add the user that you use to run Docker commands to the Docker security group. This step is not required on MacOS since Docker Desktop runs on a virtual machine as the root user.

    Linux

    The Docker security group is called docker. To add your username, run the following command:

    sudo usermod -a -G docker ${USER}
    

    Windows

    The Docker security group is called docker-users. To add a user from the Administrator command prompt, run the following command:

    net localgroup docker-users DOMAIN\USERNAME /add
    

    Where

    • DOMAIN is your Windows domain.
    • USERNAME is your user name.
  4. Log out and log back in for group membership changes to take effect. If you are using a virtual machine, you may need to restart the virtual machine for membership changes to take effect.

  5. To ensure that Docker is running, run the following Docker command, which returns the current time and date:

  6. docker run --rm busybox date
    

    The --rm flag deletes the container instance on exit.

Create a Docker repository

Create a Docker repository to store the sample image for this quickstart.

Console

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. Click Create Repository.

  3. Specify quickstart-docker-repo as the repository name.

  4. Choose Docker as the format.

  5. Under Location Type, select Region and then choose the location us-central1.

  6. Click Create.

The repository is added to the repository list.

gcloud

  1. Run the following command to create a new Docker repository named quickstart-docker-repo in the location us-central1 with the description "docker repository".

    gcloud artifacts repositories create quickstart-docker-repo --repository-format=docker \
    --location=us-central1 --description="Docker repository"
    
  2. Run the following command to verify that your repository was created.

    gcloud artifacts repositories list
    

For more information about Artifact Registry commands, run the command gcloud artifacts.

Configure authentication

Before you can push or pull images, configure Docker to use the gcloud command-line tool to authenticate requests to Artifact Registry.

To set up authentication to Docker repositories in the region us-central1, run the following command:

gcloud auth configure-docker us-central1-docker.pkg.dev

The command updates your Docker configuration. You can now connect with Artifact Registry in your Google Cloud project to push and pull images.

For information about other authentication methods, see Authentication methods.

Obtain an image to push

For this quickstart, you will push a sample image named hello-app.

  1. Change to a directory where you want to save the image.
  2. Run the following command to pull version 1.0 of the image.

    docker pull us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0
    

Add the image to the repository

Before you push the Docker image to Artifact Registry, you must tag it with the repository name.

Tag the image with a registry name

Tagging the Docker image with a repository name configures the docker push command to push the image to a specific location. For this quickstart, the host location is us-central1-docker.pkg.dev.

Run the following command to tag the image as quickstart-image:tag1:

docker tag us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0 \
us-central1-docker.pkg.dev/PROJECT/quickstart-docker-repo/quickstart-image:tag1

Where

  • PROJECT is your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
  • us-central1 is the repository location.
  • docker.pkg.dev is the hostname for Docker repositories.
  • quickstart-image is the image name you want to use in the repository. The image name can be different than the local image name.
  • tag1 is a tag you're adding to the Docker image. If you didn't specify a tag, Docker will apply the default tag latest.

You are now ready to push the image to the repository you created.

Push the image to Artifact Registry

After you have configured authentication and tagged the local image, you can push the image to the repository that you created.

To push the Docker image, run the following command:

docker push us-central1-docker.pkg.dev/PROJECT/quickstart-docker-repo/quickstart-image:tag1

Replace PROJECT with your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.

Pull the image from Artifact Registry

To pull the image from Artifact Registry onto your local machine, run the following command:

docker pull us-central1-docker.pkg.dev/PROJECT/quickstart-docker-repo/quickstart-image:tag1

Replace PROJECT with your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.

You should see output similar to the following:

latest: Pulling from [PROJECT-ID]/quickstart-image:tag1
Digest: sha256:70c42...
Status: Image is up to date for us-central1-docker.pkg.dev/PROJECT/quickstart-docker-repo/quickstart-image:tag1

Clean up

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

Before you remove the repository, ensure that any images you want to keep are available in another location.

To delete the repository:

Console

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. In the repository list, select the quickstart-docker-repo repository.

  3. Click Delete.

gcloud

To delete the quickstart-docker-repo repository, run the following command:

gcloud artifacts repositories delete quickstart-docker-repo --location=us-central1

What's next