docs/docker-for-ibm-cloud/ibm-registry.md

description	keywords	title
Use Docker images stored in IBM Cloud Container Registry	ibm, ibm cloud, registry, iaas, tutorial	Use images stored in IBM Cloud Container Registry

Use IBM Cloud Container Registry to securely store your Docker images

IBM Cloud Container Registry works with Docker EE for IBM Cloud to provide a secure image registry to use when creating swarm services and containers.

Install the CLI and set up a namespace

Follow the Getting Started with IBM Cloud Container Registry instructions to install the registry CLI and set up a namespace.

Log in to Docker with private registry credentials

Log in with IBM Cloud Container Registry

You can place the credentials of your IBM Cloud account into Docker by running the registry login command:

$ bx cr login

The bx cr login command periodically expires, so you might need to run the command again when working with Docker or use a token.

Log in with IBM Cloud Container Registry tokens

To prevent repeatedly logging in with bx cr login, you can create a non-expiring registry token with read-write permissions to use with Docker. Each token that you create is unique to the registry region. Repeat the steps for each registry region that you want to use with Docker.

1. Create a registry token.
2. Instead of using the bx cr login command, log in to Docker with the registry token. Target the region for which you are using the registry, such as ng for US South:

   $ docker login -u token -p my_registry_token registry.ng.bluemix.net
   

Log in with other private registries

You can also log in to Docker with other private registries. View that registry's documentation for the appropriate authentication methods. To use Docker Trusted Registry, configure external IBM Cloud Object Storage.

Log in before running certain Docker commands

Log in to Docker (whether by the registry log-in, token, or other method) before running the following Docker commands:

• docker pull to download an image from IBM Cloud Container Registry.
• docker push to upload an image to IBM Cloud Container Registry.
• docker service create to create a service that uses an image that is stored in IBM Cloud Container Registry.
• Any Docker command that has the --with-registry-auth parameter.

Create a container using an IBM Cloud Container Registry image

You can create a container using a registry image. You might want to run the image locally to test it before creating a swarm service based on the image.

Before you begin:

• Install the registry CLI and set up a namespace.
• Add an image in your registry namespace to use to create the swarm service.
• Log in to Docker with the appropriate registry credentials.

To create a local container that uses an IBM Cloud Container Registry image:

1. Get the name and tag of the image you want to use to create the service:

   $ bx cr images
   

2. Run the image locally:

   $ docker run --name my_container my_image:tag
   

Tip: If you no longer need the container, use the docker kill command to remove it.

Create a swarm service using an IBM Cloud Container Registry image

You can create a service that schedules tasks to spawn containers that are based on an image in your IBM Cloud Container Registry.

Before you begin:

• Install the Docker for IBM Cloud CLI.
• Install the registry CLI and set up a namespace.
• Add an image in your registry namespace to use to create the service.
• Log in to Docker with the appropriate registry credentials.
• Create a Docker swarm.

To create a Docker swarm service that uses an IBM Cloud Container Registry image:

1. Get the name and tag of the image you want to use to create the service:

   $ bx cr images
   

2. Connect to your Docker for IBM Cloud swarm. Navigate to the directory where you downloaded the UCP credentials and run the script. For example:

   $ cd filepath/to/certificate/repo && source env.sh
   

3. Send the registry authentication details when creating the Docker service for the image <your-image:tag>:

   $ docker service create --name my_service --with-registry-auth my_image:tag
   

4. Verify that your service was created:

   $ docker service ls --filter name=my_service
   

More about creating Docker services

You can also use the docker service create command options to set additional features such as replicas, global mode, or secrets. Visit the Docker swarm services documentation to learn more.