Using Docker Compose with Private Repositories

Introduction

Docker Compose is a tool for defining and running multi-container Docker applications. It allows developers to define their application stack as a YAML file, making it easy to spin up complex environments with just a few commands. However, using private repositories with Docker Compose can be tricky. In this article, we'll explore how to use Docker Compose with private repositories, covering different authentication methods and their examples.

What are Private Repositories?

Docker images can be stored in private or public repositories. Public repositories are open to everyone, while private repositories require authentication to access them. Private repositories are often used for images that contain proprietary code or data that should not be publicly available. To access a private repository, you need to provide authentication credentials.

Using Docker Compose with Private Repositories

When using Docker Compose with private repositories, you need to make sure that Docker daemon running on host machine has access to repository. There are several ways to achieve this, depending on authentication method used by repository.

Authentication Methods

Docker Config.json File

The Docker daemon can use a config.json file to store authentication credentials. This file can be created manually or using docker login command. To use a config.json file with Docker Compose, you need to mount it as a volume in your container. Here's an example ?

version: '3.8'

services:
   app:
      image: myprivaterepo/myapp
      volumes:
         - $HOME/.docker/config.json:/root/.docker/config.json

In this example, we're mounting config.json file located in user's home directory to container's root directory. This allows Docker daemon running inside container to access credentials stored in file.

Environment Variables

Some private repositories support authentication via environment variables. This method is useful when you don't want to expose your credentials in a config file. Here's an example ?

version: '3.8'

services:
   app:
      image: myprivaterepo/myapp
      environment:
         - REGISTRY_USERNAME=username
         - REGISTRY_PASSWORD=password

In this example, we're setting REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables to authentication credentials. Docker daemon running inside container can then use these variables to authenticate with repository.

Docker Compose .env File

Docker Compose allows you to define environment variables in a .env file, which is automatically loaded when you run docker-compose command. Here's an example ?

version: '3.8'

services:
   app:
      image: myprivaterepo/myapp
      env_file:
         - .env

In this example, we're using env_file directive to load environment variables defined in .env file. Here's what .env file might look like ?

REGISTRY_USERNAME=username
REGISTRY_PASSWORD=password

This method is similar to using environment variables directly in YAML file, but it allows you to keep your credentials in a separate file.

Examples

Private Repository with Docker Config.json File

Let's say we have a private repository hosted on Docker Hub, and we want to use it in a Docker Compose file. We'll start by creating a config.json file with our authentication credentials ?

{
   "auths": {
      "https://index.docker.io/v1/": {
         "auth": "dXNlcm5hbWU6cGFzc3dvcmQ="
		}
	}
}

In this example, we're using a base64-encoded string for our authentication credentials. string consists of username and password separated by a colon and encoded

Now, let's create a Docker Compose file that uses our private repository ?

version: '3.8'

services:
   app:
      image: myprivaterepo/myapp
      volumes:
         - $HOME/.docker/config.json:/root/.docker/config.json

In this example, we're defining a service called "app" that uses image "myprivaterepo/myapp" from our private repository. We're also mounting config.json file as a volume in container so that Docker daemon running inside container can access credentials.

To run this Docker Compose file, we can use following command ?

docker-compose up

This will start "app" service and pull image from our private repository.

Private Repository with Environment Variables

Let's say we have a private repository hosted on a self-hosted registry, and we want to use it in a Docker Compose file. We'll start by setting our authentication credentials as environment variables ?

export REGISTRY_USERNAME=username
export REGISTRY_PASSWORD=password

Now, let's create a Docker Compose file that uses our private repository ?

version: '3.8'

services:
   app:
      image: myprivaterepo/myapp
      environment:
         - REGISTRY_USERNAME=$REGISTRY_USERNAME
         - REGISTRY_PASSWORD=$REGISTRY_PASSWORD

In this example, we're defining a service called "app" that uses image "myprivaterepo/myapp" from our private repository. We're also setting REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables to our authentication credentials.

To run this Docker Compose file, we can use following command ?

docker-compose up

This will start "app" service and pull image from our private repository.

• Private Repository with Docker Compose .env File

Let's say we have a private repository hosted on a self-hosted registry, and we want to use it in a Docker Compose file. We'll start by creating a .env file with our authentication credentials ?

REGISTRY_USERNAME=username
REGISTRY_PASSWORD=password

Now, let's create a Docker Compose file that uses our private repository ?

version: '3.8'

services:
   app:
      image: myprivaterepo/myapp
      env_file:
         - .env

In this example, we're defining a service called "app" that uses image "myprivaterepo/myapp" from our private repository. We're also using env_file directive to load environment variables defined in .env file.

To run this Docker Compose file, we can use following command ?

docker-compose up

This will start "app" service and pull image from our private repository.

Private Repository with Docker Configurations

If you are running Docker on a swarm, you can use Docker configurations to store your authentication credentials. To use Docker configurations in Docker Compose, we'll need to create a configuration file that contains our authentication credentials ?

echo "password" | docker secret create registry_password -
echo "username" | docker secret create registry_username -

Now, let's create a Docker Compose file that uses our private repository ?

version: '3.8'

services:
   app:
      image: myprivaterepo/myapp
      secrets:
         - registry_username
         - registry_password

In this example, we're defining a service called "app" that uses image "myprivaterepo/myapp" from our private repository. We're also using secrets directive to load registry_username and registry_password secrets into container.

To run this Docker Compose file, we can use following command ?

docker-compose up

This will start "app" service and pull image from our private repository.

Private Repository with Docker Build

If you're building a Docker image that uses a private repository, you can use Docker build to authenticate with your private repository. Here's an example ?

docker build --build-arg REGISTRY_USERNAME=username --build-arg REGISTRY_PASSWORD=password -t myprivaterepo/myapp .

In this example, we're building an image called "myprivaterepo/myapp" that uses a private repository. We're passing our authentication credentials as build arguments using --build-arg.

Once image is built, we can use it in our Docker Compose file ?

version: '3.8'

services:
   app:
      image: myprivaterepo/myapp

In this example, we're defining a service called "app" that uses image "myprivaterepo/myapp" from our private repository.

To run this Docker Compose file, we can use following command ?

docker-compose up

This will start "app" service and use image from our private repository.

Conclusion

Using Docker Compose with private repositories can be challenging, but there are several authentication methods available that make it easier to access your images. In this article, we explored how to use Docker Compose with private repositories, covering different authentication methods and their examples. By following these examples, you can easily authenticate with your private repositories and use your images in Docker Compose.