If your server is behind a firewall, don’t forget toallowlist the domains you’d like to pull images from.

Use images from a private Docker registry

The Docker-based runner can be configured to pull versions of the public Atlassian docker images from a private docker registry that allows authentication using a username and password.

To use a private Docker image hosted on a Docker registry (such asDocker Hub), create or update the.docker/config.json file with login credentials for the Docker registry. The use of authentication credentials other than basic authentication (a username with a password), such as tokens and timed passwords is not supported. The use of acredential store is also not supported.

A.docker/config.json file can be created either by:

• Using the Docker login command

• Manually creating the Docker config.json file

Using the Docker login command

To create or update the~/.docker/config.json file with login credentials:

1. On the runner host, run the following command and provide your username and password when prompted:

   docker login <registry_hostname>

   • If the login is successful, you will receive a warning about unencrypted storage of your password and the messageLogin Succeeded.

   • If you don't receive the warning, the docker instance on the host may be configured to usea credential store, which is not supported.

2. Mount the host.docker/config.json file in the runner container using the volume flag (-v), such as:

   -v <path_to_docker_config_directory>/.docker:/root/.docker

   Where the default location for<path_to_docker_config_directory>/.docker is~/.docker/.

   For example:

   docker container run \-v /var/run/docker.sock:/var/run/docker.sock \-v /var/lib/docker/containers:/var/lib/docker/containers:ro \-v <path_to_docker_config_directory>/.docker/config.json:/root/.docker/config.json \-e ACCOUNT_UUID=<my-account-id> \-e REPOSITORY_UUID=<my-repository-id> \-e RUNNER_UUID=<my-runner-id> \-e OAUTH_CLIENT_ID=<my-oauthclient-id> \-e OAUTH_CLIENT_SECRET=<my-oauthclient-secret> \-e WORKING_DIRECTORY=/tmp \-e RUNTIME_PREREQUISITES_ENABLED=true \-e PAUSE_IMAGE="my-private-registry/my-pause:latest" \-e AUTH_PROXY_IMAGE="my-private-registry/my-auth-proxy:latest" \-e CLONE_IMAGE="my-private-registry/my-clone:latest" \--name my-runner-b0ae87b8-423b-5c24-9a95-84ddad9cdfae \docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runner

Manually creating the Docker config.json file

To manually create or update the~/.docker/config.json file with login credentials:

1. On the runner host, use a plain text editor to create or open the.docker/config.json file in the user's home directory.

2. Add or append theauths top-level property, such as:

   { "auths": { "my-private-registry-uri": { "auth": "dXNlcjpwYXNzd29yZA==" }, "my-other-private-registry-uri": { "auth": "dXNlcjE6cGFzc3dvcmQx" } }}

   Wheremy-private-registry-uri andmy-other-private-registry-uri are the URLs of two private registries, such as Docker Hub. Theauth values are the username and password for registries (colon-separated) after they have beenbase64 encoded. To base64 encode the username and password on a macOS or Linux command line, run:

   echo -n 'user:password' | base64

    

3. Mount the host.docker/config.json file in the runner container using the volume flag (-v), such as:

   -v <path_to_docker_config_directory>/.docker:/root/.docker

   Where the default location for<path_to_docker_config_directory>/.docker is~/.docker/.

   For example:

   docker container run \-v /var/run/docker.sock:/var/run/docker.sock \-v /var/lib/docker/containers:/var/lib/docker/containers:ro \-v <path_to_docker_config_directory>/.docker/config.json:/root/.docker/config.json \-e ACCOUNT_UUID=<my-account-id> \-e REPOSITORY_UUID=<my-repository-id> \-e RUNNER_UUID=<my-runner-id> \-e OAUTH_CLIENT_ID=<my-oauthclient-id> \-e OAUTH_CLIENT_SECRET=<my-oauthclient-secret> \-e WORKING_DIRECTORY=/tmp \-e RUNTIME_PREREQUISITES_ENABLED=true \-e PAUSE_IMAGE="my-private-registry/my-pause:latest" \-e AUTH_PROXY_IMAGE="my-private-registry/my-auth-proxy:latest" \-e CLONE_IMAGE="my-private-registry/my-clone:latest" \--name my-runner-b0ae87b8-423b-5c24-9a95-84ddad9cdfae \docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runner

Limitations

This feature has the following limitations:

• Authentication using acredential store is not supported. Only login using basic authentication (username and password) is supported.

• The images must be hosted in a registry. The runner will always pull images from a remote host and can't use images on the host device.

• This feature is only available to Docker self-hosted runners. Other runners (such as shell-based runners) don't use containers.