Before You Begin

This 10-minute tutorial shows you how to:

• create an auth token for use with Oracle Cloud Infrastructure Registry
• create a new repository
• 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. Having created a new repository, 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 client machine as described in this tutorial, you'll need to have installed Docker on the local machine. (Alternatively, you could use Docker in the Cloud Shell environment.)

Start Oracle Cloud Infrastructure

1. In a browser, go to the url you've been given to log in to Oracle Cloud Infrastructure.



2. 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.
3. Enter your username and password, and click Sign In. This tutorial assumes the username is jdoe@acme.com.

Get an Auth Token and Create a New Repository

1. In the top-right corner of the Console, open the User menu (), and then click User Settings.



2. On the Auth Tokens page, click Generate Token.



3. Enter Tutorial auth token as a friendly description for the auth token and click Generate Token. The new auth token is displayed.
4. 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.
5. Close the Generate Token dialog.
6. Confirm that you can access Oracle Cloud Infrastructure Registry:
   1. In the Console, open the navigation menu. Under Solutions and Platform, go to Developer Services and click Container Registry.
   2. Choose the region in which you will be working (for example, us-phoenix-1).
   3. Choose a compartment you have permission to work in.
   4. Review the repositories that already exist. This tutorial assumes that no repositories have been created yet.

      

7. Create a new repository:
   1. Click Create Repository.
   2. Choose the compartment in which to create the new repository (by default, the same compartment you selected previously).
   3. Enter helloworld as the name for the new repository.
   4. Select the Private option to limit access to the new repository.
   5. Click Create Repository to create the new repository.

      

Login 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-key>.ocir.io

   where <region-key> is the key for the Oracle Cloud Infrastructure Registry region you're using. For example, phx. See the Availability by Region topic in the Oracle Cloud Infrastructure Registry documentation.
2. When prompted, enter your username in the format <tenancy-namespace>/<username>. For example, ansh81vru1zp/jdoe@acme.com. If your tenancy is federated with Oracle Identity Cloud Service, use the format <tenancy-namespace>/oracleidentitycloudservice/<username>.
3. When prompted, enter the auth token you copied earlier as the password.

Pull 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.

   

   The different layers of the helloworld image are each pulled in turn.

Tag 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-key>.ocir.io/<tenancy-namespace>/<repo-name>:<tag>

   where:
   • <region-key> is the key for the Oracle Cloud Infrastructure Registry region you're using. For example, phx. See the Availability by Region topic in the Oracle Cloud Infrastructure Registry documentation.
   • ocir.io is the Oracle Cloud Infrastructure Registry name.
   • <tenancy-namespace> is the auto-generated Object Storage namespace string of the tenancy (as shown on the Tenancy Information page) to which you want to push the image. For example, the namespace of the acme-dev tenancy might be ansh81vru1zp. Note that your user must have access to the tenancy.
   • <repo-name> is the name of the target repository to which you want to push the image (for example, helloworld). Note that you'll usually specify a repository that already exists.
   • <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/ansh81vru1zp/helloworld:latest



2. Review the list of available images by entering:

   docker images

   

   Note that although two tagged images are shown, both are based on the same image (with the same image id).

Push 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-key>.ocir.io/<tenancy-namespace>/<repo-name>:<tag>

   where:
   • <region-key> is the key for the Oracle Cloud Infrastructure Registry region you're using. For example, phx. See the Availability by Region topic in the Oracle Cloud Infrastructure Registry documentation.
   • ocir.io is the Oracle Cloud Infrastructure Registry name.
   • <tenancy-namespace> is the auto-generated Object Storage namespace string of the tenancy (as shown on the Tenancy Information page) that owns the repository to which you want to push the image. For example, the namespace of the acme-dev tenancy might be ansh81vru1zp. Note that your user must have access to the tenancy.
   • <repo-name> is the name of the target repository to which you want to push the image (for example, helloworld). Note that you'll usually specify a repository that already exists.
   • <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/ansh81vru1zp/helloworld:latest

   

   The different layers of the helloworld image are each pushed in turn.

Verify 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 you created.



2. 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.



3. 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:

   ## Hello World example
   by Karthequian [Pulled from Dockerhub](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 )

   

3. Click the Preview tab to see how the readme will appear.

   

4. Click Save to close the Edit Readme dialog.
4. 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.



5. (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/ansh81vru1zp/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.

Housekeeping (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.

Want to Learn More?

• Overview of Registry
• Pushing Images Using the Docker CLI
• Pulling an Image from Oracle Cloud Infrastructure Registry when Deploying a Load-Balanced Application to a Cluster