Oracle by Example brandingPushing an Image to Oracle Cloud Infrastructure Registry

section 0Before You Begin

This 10-minute tutorial shows you how to:

  • create an auth token for use with Oracle Cloud Infrastructure Registry
  • log in to Oracle Cloud Infrastructure Registry from the Docker CLI
  • pull a test image from DockerHub
  • tag the image
  • push the image to Oracle Cloud Infrastructure Registry using the Docker CLI
  • verify the image has been pushed to Oracle Cloud Infrastructure Registry using the Console

Background

Oracle Cloud Infrastructure Registry is an Oracle-managed registry that enables you to simplify your development to production workflow. Oracle Cloud Infrastructure Registry makes it easy for you as a developer to store, share, and manage development artifacts like Docker images. And the highly available and scalable architecture of Oracle Cloud Infrastructure ensures you can reliably deploy your applications. So you don't have to worry about operational issues, or scaling the underlying infrastructure.

In this tutorial, you'll first create an auth token to access Oracle Cloud Infrastructure Registry. You'll then pull a test image from DockerHub and give it a new tag. The new tag identifies the Oracle Cloud Infrastructure Registry region, tenancy, and repository to which you want to push the image.

Having given the image the tag, you then push it to Oracle Cloud Infrastructure Registry using the Docker CLI. Finally, you'll verify the image has been pushed successfully by viewing the repository that has been created.

What Do You Need?

  • An Oracle Cloud Infrastructure username and password.
  • To push images to Oracle Cloud Infrastructure Registry, you must belong to one of the following:
    • The tenancy's Administrators group.
    • A group to which a policy grants the appropriate Oracle Cloud Infrastructure Registry permissions, including the REPOSITORY_CREATE permission (see the Policies to Control Repository Access topic in the Oracle Cloud Infrastructure Registry documentation).
  • Access to the Docker CLI (for example, to push and pull images on a local machine, you'll need to have installed Docker on the local machine).

section 1Start Oracle Cloud Infrastructure

  1. In a browser, go to the url you've been given to log in to Oracle Cloud Infrastructure.
  2. Description of the illustration
  3. Specify a tenancy in which you have the appropriate permissions to create repositories in Oracle Cloud Infrastructure Registry. You inherit these permissions in one of the following ways:
    • by belonging to the tenancy's Administrators group
    • by belonging to another group to which a policy grants the appropriate Oracle Cloud Infrastructure Registry permissions, including the REPOSITORY_CREATE permission
    This tutorial assumes the tenancy is acme-dev.
  4. Enter your username and password, and click Sign In. This tutorial assumes the username is jdoe@acme.com.

section 2Get an Auth Token

  1. In the top-right corner of the Console, click your username, and then click User Settings.
  2. Description of the illustration
  3. On the Auth Tokens page, click Generate Token.
  4. Description of the illustration
  5. Enter Tutorial auth token as a friendly description for the auth token and click Generate Token. The new auth token is displayed.
  6. Copy the auth token immediately to a secure location from where you can retrieve it later, because you won't see the auth token again in the Console.
  7. Close the Generate Token dialog.
  8. Confirm that you can access Oracle Cloud Infrastructure Registry:
    1. In the Console, open the navigation menu. Under Solutions, Platform and Edge, go to Developer Services and click Registry.
    2. Choose the region in which you will be working (for example, us-phoenix-1). 
    3. Review the repositories that already exist. This tutorial assumes that no repositories have been created yet.
      Description of the illustration

section 3Login to Oracle Cloud Infrastructure Registry from the Docker CLI

  1. In a terminal window on the client machine running Docker, log in to Oracle Cloud Infrastructure Registry by entering:
    docker login <region-code>.ocir.io
    where <region-code> corresponds to the code for the Oracle Cloud Infrastructure Registry region you're using, as follows:
    • enter fra as the region code for Frankfurt
    • enter iad as the region code for Ashburn
    • enter lhr as the region code for London
    • enter phx as the region code for Phoenix
  2. When prompted, enter your username in the format <tenancy_name>/<username>. For example, acme-dev/jdoe@acme.com. If your tenancy is federated with Oracle Identity Cloud Service, use the format <tenancy-name>/oracleidentitycloudservice/<username>.
  3. When prompted, enter the auth token you copied earlier as the password.
    Description of the illustration

section 4Pull the hello-world Image from DockerHub

  1. In a terminal window on the client machine running Docker, enter docker pull karthequian/helloworld:latest to retrieve the latest version of the hello-world image from DockerHub.
    Description of the illustration
    The different layers of the helloworld image are each pulled in turn.

section 5Tag the Image for Pushing

  1. In a terminal window on the client machine running Docker, give a tag to the image that you're going to push to Oracle Cloud Infrastructure Registry by entering:
    docker tag karthequian/helloworld:latest
    <region-code>.ocir.io/<tenancy-name>/<repo-name>/<image-name>:<tag>
    where:
    • <region-code> is one of fra, iad, lhr, or phx.
    • ocir.io is the Oracle Cloud Infrastructure Registry name.
    • <tenancy-name> is the name of the tenancy to which you want to push the image (for example, acme-dev). Note that your user must have access to the tenancy.
    • <repo-name> (if specified) is the name of a repository to which you want to push the image (for example, project01). Note that specifying a repository is optional. If you don't specify a repository name, the name of the image is used as the repository name in Oracle Cloud Infrastructure Registry.
    • <image-name> is the name you want to give the image in Oracle Cloud Infrastructure Registry (for example, helloworld).
    • <tag> is an image tag you want to give the image in Oracle Cloud Infrastructure Registry (for example, latest).
    For example:
    docker tag karthequian/helloworld:latest
    phx.ocir.io/acme-dev/helloworld:latest
  2. Description of the illustration
  3. Review the list of available images by entering:
    docker images
    Description of the illustration
    Note that although two tagged images are shown, both are based on the same image (with the same image id).

section 6Push the hello-world Image to Oracle Cloud Infrastructure Registry

  1. In a terminal window on the client machine running Docker, push the Docker image from the client machine to Oracle Cloud Infrastructure Registry by entering:
    docker push
    <region-code>.ocir.io/<tenancy-name>/<repo-name>/<image-name>:<tag>
    where:
    • <region-code> is one of fra, iad, lhr, or phx.
    • ocir.io is the Oracle Cloud Infrastructure Registry name.
    • <tenancy-name> is the name of the tenancy that owns the repository to which you want to push the image (for example, acme-dev). Note that your user must have access to the tenancy.
    • <repo-name> (if specified) is the name of a repository to which you want to push the image (for example, project01). Note that specifying a repository is optional. If you don't specify a repository name, the name of the image is used as the repository name in Oracle Cloud Infrastructure Registry.
    • <image-name> is the name you want to give the image in Oracle Cloud Infrastructure Registry (for example, helloworld).
    • <tag> is an image tag you want to give the image in Oracle Cloud Infrastructure Registry (for example, latest).
    For example:
    docker push phx.ocir.io/acme-dev/helloworld:latest
    Description of the illustration
    The different layers of the helloworld image are each pushed in turn.

section 7Verify the Image has been Pushed to Oracle Cloud Infrastructure Registry

  1. In the browser window showing the Console with the Registry page displayed, click Reload. You see all the repositories in the registry to which you have access, including the private helloworld repository that was created when you pushed the helloworld image.
  2. Description of the illustration
  3. Click the name of the helloworld repository that contains the image you just pushed. You see:
    • The different images in the repository. In this case, there is only one image, with the tag latest.
    • Details about the repository, including who created it and when, its size, and whether it's a public or a private repository
    • The readme associated with the repository. In this case, there is no readme yet.
    Description of the illustration
  4. Provide a readme for the helloworld repository as follows:
    1. Click the Edit button in the Readme section.
    2. On the Edit tab of the Edit Readme dialog, select the Markdown option, and copy and paste the following description of the helloworld image into the Content field:
      ## (https://hub.docker.com/r/karthequian/helloworld/)
      ![Helloworld by Karthquian](https://raw.githubusercontent.com/oracle/cloud-native-devops-workshop/master/containers/docker001/images/004-hello-world.png )
      Description of the illustration
    3. Click the Preview tab to see how the readme will appear.
      Description of the illustration
    4. Click Save to close the Edit Readme dialog.
  5. Click the latest image tag. The Details section shows you the size of the image, when it was pushed and by which user, and the number of times the image has been pulled.
  6. Description of the illustration
  7. (Optional) Later on, if you want to pull the image, click the Actions button beside the image name and select Copy Pull Command. For example, the command might be:
    docker pull phx.ocir.io/acme-dev/helloworld:latest
    Congratulations! You've successfully pulled the helloworld image from DockerHub, tagged it, and pushed it to Oracle Cloud Infrastructure Registry using the Docker CLI. You've verified that the image was pushed successfully, and you've added a description in the readme.

section 8Housekeeping (optional)

Having completed the tutorial, if you want to free up Oracle Cloud Infrastructure resources, you can now delete the helloworld repository. On the other hand, you might want to retain it for your own testing purposes. If you intend to follow the Pulling an Image from Oracle Cloud Infrastructure Registry when Deploying a Load-Balanced Application to a Cluster tutorial, definitely don't delete the helloworld repository because you will use it in that tutorial.

  1. (optional) In the browser window showing the Console with the Registry page displayed:
    1. Click the name of the helloworld repository.
    2. Click the Actions button beside the repository name and select Delete Repository.
    3. Confirm that you want to delete the repository.

more informationWant to Learn More?