Page tree
Skip to end of metadata
Go to start of metadata

Artifactory as a Docker Registry

Artifactory lets you use repositories as full-fledged local Docker registries in every way.

On top of Artifactory's existing support for advanced artifact management, Artifactory support for Docker provides:

  1. Distribution and sharing of Docker images within your organization
  2. Secure Docker push and pull using a local private registry
  3. Extensive security features that give you fine-grained access control over registries and images.
  4. Reliable and consistent access to Docker images
  5. Smart search for images
  6. Support for the relevant calls of the Docker Registry API and Docker Hub API so that you can transparently use the Docker client to access images through Artifactory.
  7. Integration with Bintray for automated distribution of Docker images

Support for Docker starts with Artifactory version 3.4, and from version 3.7, Artifactory also supports the Docker V2 Registry API. 

Running Artifactory as a Docker container

Artifactory is also available on Bintray as a Docker image and can be run as a container. For more details, please refer to Running with Docker.

Compatibility Table

Artifactory is continuously updated to support the latest version of Docker. To make sure your versions of Artifactory and Docker are compatible, please refer to the following table:

Artifactory Version

Docker Client Version

Docker V1 API

Docker V2 API

3.9.41.8(tick)(tick)
3.7+1.7(tick)(tick)
3.4+1.7(tick)

(error)

Configuring Artifactory

Local Repositories

To enable Docker images support in local repositories, in the Edit Local Repository dialog, select the Packages tab and check Enable Docker Support:

Remote Repositories

Docker version

Note that remote Docker repositories are only supported for Docker V2.

Remote Repository defined in Artifactory serves as a caching proxy for a registry managed at a remote URL such as https://registry-1.docker.io (the Docker Hub).

Docker images requested from a remote repository are cached on demand. You can remove downloaded images from the remote repository cache, however you can not manually push Docker images to a remote Docker repository.

To define a remote repository to proxy a remote Docker registry follow the steps below:

  1. In the Admin tab under Configuration | Repositories  go to the Remote Repositories section and select "New" 
  2. Set the Repository Key value, and specify the URL to the remote registry in the URL field as displayed below
  3. In the Packages tab of the New Remote Repository dialog, set Enable Docker Support and click "Create"

    Proxying the official Docker Hub

    If you are proxying the official Docker Hub, use https://registry-1.docker.io as the URL and make sure to check the Enable Token Authentication checkbox as well since the Docker Hub only supports token based authentication.

 

 

Page Contents


Requirement for a Reverse Proxy (Nginx/Apache)

The Docker client presents some limitations:

  1. You cannot provide a context path when providing the registry path (e.g localhost:8080/artifactory is not valid)
  2. Docker will only send basic HTTP authentication when working against an HTTPS host

As a result, Artifactory can only be used with Docker through a reverse proxy.

Using a Self-signed SSL Certificate

From Docker version 1.3.1, you can use self-signed SSL certificates with docker push/pull commands, however for this to work, you need to specify the --insecure-registry daemon flag for each insecure registry.

For full details please refer to the Docker documentation.

For example, if you are running Docker as a service, edit the /etc/default/docker file, and append the --insecure-registry flag with your registry URL to the DOCKER_OPTS variable as in the following example:

Edit the DOCKER_OPTS variable
DOCKER_OPTS="-H unix:///var/run/docker.sock --insecure-registry artprod.company.com"

For this to take effect, you need to restart the Docker service.

If you are using Boot2Docker, please refer to the Boot2Docker documentation for Insecure Registry.

If you do not make the required modifications to the --insecure-registry daemon flag, you should get the following error:

Error message
 Error: Invalid registry endpoint https://artprod.company.com/v1/: Get https://artprod.company.com/v1/_ping: x509: certificate signed by unknown authority.

Using previous versions of Docker

In order to use self-signed SSL certificates with previous versions of Docker, you need to manually install the certificate into the OS of each machine running the Docker client (see Issue 2687).

Configuring a Reverse Proxy

Docker push and pull commands are in the form of:

docker push/pull [registry_hostname[:port]/][user_name/](repository_name:version_tag)

 

Below are sample configurations for Nginx and Apache which configure SSL on port 443 and a server name of artprod.company.com:

Nginx Configuration

Notice that the configuration below binds the 443 port of nginx to a specific local repository in Artifactory (named docker-local or docker-local2).

If you want to use multiple repositories, you need to copy this configuration and bind different ports to each local repository in Artifactory.

When binding a port other than 443, note that the configuration for the proxy header must be appended with the port number on the proxy_set_header line. For example, for a server running on port 444 you should write proxy_set_header Host $host:444.

nginx 1.3.9 or later required

This code requires nginx to support chunked transfer encoding which is available from nginx v1.3.9.

 nginx config for docker V1
[...]
 
http {
	
	##
	# Basic Settings
	##
	[...]
 
	server {
  		listen 443;
  		server_name artprod.company.com;

	  	ssl on;
  		ssl_certificate /etc/ssl/certs/artprod.company.com.crt;
  		ssl_certificate_key /etc/ssl/private/artprod.company.com.key;

  		access_log /var/log/nginx/artprod.company.com.access.log;
  		error_log /var/log/nginx/artprod.company.com.error.log;

  		proxy_set_header Host $host;
  		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  		proxy_set_header X-Real-IP $remote_addr;
  		proxy_set_header X-Forwarded-Proto $scheme;
  		proxy_set_header X-Original-URI $request_uri;
  		proxy_read_timeout 900;

  		client_max_body_size 0; # disable any limits to avoid HTTP 413 for large image uploads

  		# required to avoid HTTP 411: see Issue #1486 (https://github.com/docker/docker/issues/1486)
  		chunked_transfer_encoding on;

  		location /v1 {
    		proxy_pass http://artprod.company.com:8080/artifactory/api/docker/docker-local/v1;
		}
	}
}
 nginx config for docker V2
[...]

http {
	

	##
	# Basic Settings
	##

	[...]
 
	server {
  		listen 443;
  		server_name artprod2.company.com;

  		ssl on;
  		ssl_certificate /etc/ssl/certs/artprod2.company.com.crt;
  		ssl_certificate_key /etc/ssl/private/artprod2.company.com.key;

  		access_log /var/log/nginx/artprod2.company.com.access.log;
  		error_log /var/log/nginx/artprod2.company.com.error.log;

  		proxy_set_header Host $host;
  		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  		proxy_set_header X-Real-IP $remote_addr;
  		proxy_set_header X-Forwarded-Proto $scheme;
  		proxy_set_header X-Original-URI $request_uri;
  		proxy_read_timeout 900;

  		client_max_body_size 0; # disable any limits to avoid HTTP 413 for large image uploads

  		# required to avoid HTTP 411: see Issue #1486 (https://github.com/docker/docker/issues/1486)
  		chunked_transfer_encoding on;

  		location /v2 {
    		proxy_pass http://artprod2.company.com:8080/artifactory/api/docker/docker-local2/v2;
  		}
	}
}

Apache Configuration

 Apache config for docker V1
<VirtualHost *:443>
  ServerName artprod.company.com 

  ErrorLog ${APACHE_LOG_DIR}/error.log
  CustomLog ${APACHE_LOG_DIR}/access.log combined

  SSLEngine on
  SSLCertificateFile      /etc/ssl/certs/artprod.company.com.pem
  SSLCertificateKeyFile   /etc/ssl/private/artprod.company.com.key

  ProxyRequests off
  ProxyPreserveHost on

  ProxyPass         / http://artprod.company.com:8080/artifactory/api/docker/docker-local/
  ProxyPassReverse  / http://artprod.company.com:8080/artifactory/api/docker/docker-local/
</VirtualHost>
 Apache config for docker V2
<VirtualHost *:443>
  ServerName artprod2.company.com 

  ErrorLog ${APACHE_LOG_DIR}/error.log
  CustomLog ${APACHE_LOG_DIR}/access.log combined

  SSLEngine on
  SSLCertificateFile      /etc/ssl/certs/artprod2.company.com.pem
  SSLCertificateKeyFile   /etc/ssl/private/artprod2.company.com.key

  ProxyRequests off
  ProxyPreserveHost on

  ProxyPass         / http://artprod.company.com:8080/artifactory/api/docker/docker-local2/
  ProxyPassReverse  / http://artprod.company.com:8080/artifactory/api/docker/docker-local2/
</VirtualHost>

HAProxy configuration

frontend normal 
	 bind *:80
	 bind *:443 ssl crt /etc/haproxy/ssl
	 mode http
	 option forwardfor
	 reqadd X-Forwarded-Proto:\ https if { ssl_fc }
	 option forwardfor header X-Real-IP
	 default_backend normal
frontend docker
	 bind *:5001 ssl crt /etc/haproxy/ssl
	 mode http
	 option forwardfor
	 reqadd X-Forwarded-Proto:\ https if { ssl_fc }
	 option forwardfor header X-Real-IP
	 reqirep ^([^\ :]*)\ /v1(.*$) \1\ /artifactory/api/docker/docker-prod-local/v1\2
	 reqirep ^([^\ :]*)\ /v2(.*$) \1\ /artifactory/api/docker/docker-prod-local2/v2\2
	 default_backend normal
backend normal
	mode http
	server localhost 127.0.0.1:8081  

Docker repository path must be prefixed with api/docker, and use explicit IP address

When accessing a Docker repository through Artifactory, the repository URL must be prefixed with api/docker in the path.

You can copy the full URL from the UI when you configure the local Docker repository as mentioned above.

For example, if you are using Artifactory standalone or as a local service, you would access your Docker repositories using the following URL:

http://localhost:8081/artifactory/api/docker/<repository key>

Also, the domain of your Docker repository must be expressed as an explicit IP address. The only exception is when working locally, you can use the localhost domain name.


Docker Login

You may use Artifactory with anonymous access enabled or disabled, and this affects how you set your Docker credentials.

Artifactory with Anonymous Access Disabled

With anonymous access disabled, log in to Docker in the usual way using  docker login.

Artifactory with Anonymous Access Enabled

From version 3.9.3 Artifactory supports docker login with Allow Anonymous Access enabled. 

When Allow Anonymous Access is enabled, Artifactory will not query the Docker client for authentication parameters by default, so you need to indicate to Artifactory to request authentication parameters in a different way.

You can override the default behavior by setting the artifactory.docker.forceAuthentication system property in the $ARTIFACTORY_HOME/etc/artifactory.system.properties file which will designate behavior as follows:

ValueBehavior
"false", empty or property not defined

Artifactory will attempt to access the Docker repository anonymously. If anonymous access is allowed by the repository then Artifactory will download the requested image.

Otherwise, Artifactory will return an error to the Docker client.

"true" or "all"Artifactory will first request authentication parameters from the Docker client before trying to access any Docker repository.

Comma-separated list of repositories (no spaces).

e.g. repo1,repo2,repo3...

Artifactory will first request authentication parameters from the Docker client before trying to access the specified Docker repositories. For other repositories, Artifactory will attempt anonymous access.

Restart required

You need to restart Artifactory for this change to take effect.

Setting Your Credentials Manually

If you are using Docker V1 API, or are unable to log in to Docker for any other reason, you may need to set your credentials manually.

 Manually setting your Docker credentials

The Docker command line tool supports authenticating sensitive operations, such as push, with the server using basic HTTP authentication.

To enforce authenticated access to docker repositories you need to provide the following parameters to the Docker configuration file.

  • The Docker endpoint URL (must use HTTPS for basic authentication to work)
  • Your Artifactory username and password (formatted username:password) as  Base64 encoded strings
  • Your email address

You can use the following command to get these strings directly from Artifactory and copy/paste them into your ~/.dockercfg file:

sudo

If you are using Docker commands with "sudo" or as a root user (for example after installing the Docker client), note that the Docker configuration file should locatedunder /root/.dockercfg

Getting .dockercfg entries directly from Artifactory

$ curl -uadmin:password "https://artprod.company.com/<version>/auth"
{
"https://artprod.company.com" : {
"auth" : "YWRtaW46QVA1N05OaHZTMnM5Qk02RkR5RjNBVmF4TVFl",
"email" : "admin@email.com"
}
}

Where: <version> =  v1 | v2

The Docker configuration file may contain a separate authentication block for each registry that you wish to access.

Below is an example with two URL endpoints:

{
	"https://artprod.company.com": {
		"auth":"YWRtaW46cGFzc3dvcmQ=",
		"email":"myemail@email.com"
	},
	"https://artprod2.company.com": {
		"auth":"YWRtaW46cGFzc3dvcmQ=",
		"email":"myemail@email.com"
	}
}

Docker Push 

In order to use docker push you need to tag your image with the proper reverse proxy URL described above.

For example,  to push the official Ubuntu base image into our local Artifactory repository:

# First we need to pull the official Ubuntu base image from the docker hub
$ docker pull ubuntu
 
# Next we tag it with our own endpoint URL
$ docker tag ubuntu artprod.company.com/ubuntu
 
# Finally we can push the tagged image
$ docker push artprod.company.com/ubuntu

Docker Pull

You can simply execute docker pull from the endpoint URL as defined above:

$ docker pull artprod.company.com/ubuntu

Working with Artifactory without Anonymous Access

By default, Artifactory allows anonymous access to docker repositories. This is defined under Security | General Configuration. For details please refer to Allow Anonymous Access.
If you want to be able to trace how users interact with your repositories you need to uncheck the Allow Anonymous Access setting. This means that users will be required to enter their username and password as described in Setting Your Credentials above.


Working with the Docker V2 Registry API

Working with Docker V1

If you are using Docker below version 1.6, please refer to Working with the Docker V1 Registry API.

Docker Repository Layout

Artifactory stores Docker blobs and manifests together for easy security management and deletion:

 

In addition, properties are attached to each blob and manifest to facilitate searching for them:

  • manifest - Each manifest is annotated with a property called sha256 which is its sha256 checksum as well as it's name stored in a property called docker.manifest.
  • blob - Each blob is also annotated with its sha256 checksum property.

Promoting Docker Images

From version 3.5.3, Artifactory supports promoting Docker images from one Docker repositories in Artifactory to another.

Promotion can be triggered using the following endpoint with cURL:

POST api/docker/<repoKey>/<version>/promote
{ 
    "targetRepo" : "<targetRepo>",  
    "dockerRepository" : "<dockerRepository>",  
    "tag" : "<tag>", 
    "copy": <copy>
}

where:

<repoKey>

Source repository key (For example, docker-local as used in this page)

<version>

The Docker version you are using (v1 | v2)

<targetRepo>

The target repository to move or copy

<dockerRepository>

The docker repository name to promote

<tag>

An optional tag name to promote, if null - the entire docker repository will be promoted. Default: "" 

<copy>

Whether to copy instead of move,. Default: false

 

This is useful when you need to promote Docker images, for example, from a development repository to production.

An example for promoting the docker image "jfrog/ubuntu" with all of it's tags from docker-local to docker-prod using cURL would be:

Promoting Docker Images
curl -i -uadmin:password -X POST "https://artprod.company.com/v1/promote" -H "Content-Type: application/json" -d
'{"tagetRepo":"docker-prod","dockerRepository":"jfrog/ubuntu"}'

Notice that the above example is executed through your reverse proxy. To go directly through Artifactory, you would execute this command as follows:

curl -i -uadmin:password -X POST "http://localhost:8080/artifactory/api/docker/docker-local/v1/promote" -H "Content-Type: application/json" -d
'{"targetRepo":"docker-prod","dockerRepository":"jfrog/ubuntu"}'

Working with the Docker V1 Registry API

Docker Repository Layout

Artifactory stores docker images in a layout that is made up of 2 main directories:

  • .images: Stores all the flat docker images.
  • repositories: Stores all the repository information with tags (similar to how repositories are stored in the Docker Hub).

In addition, Artifactory annotates each deployed docker image with two properties:

  • docker.imageId: The image id
  • docker.size: The size of the image in bits

Deployed tags are also annotated with two properties:

  • docker.tag.name: The tag name
  • docker.tag.content: The id of the image that this tag points to


 

Viewing the Docker Images Tree 

Artifactory lets you view the complete images tree for a specific image directly from the UI in a similar way to what you would get from the docker images --tree command.

In the Artifacts tab, select Tree Browser and drill down to select the ancestry.json file you want to inspect. The metadata is displayed in the Docker Ancestry tab.

Viewing Individual Docker image Information

Artifactory lets you view the complete images tree for a specific image directly from the UI.

In the Artifacts tab, select Tree Browser and drill down to select the json.json file you want to inspect. The metadata is displayed in the Docker Info tab.

Searching Docker Images

On top of existing properties mentioned above, Artifactory also saves another property, docker.repoName, which represents the repository name (e.g "library/ubuntu"):

Search Using the Docker Client

The Docker client natively supports searching for images in private registries.

For example, to search for the ubuntu image in artprod.company.com, use the following command: 

 docker search artprod.company.com/ubuntu

However, since the Docker client does  not send authentication credentials, this requires that you have anonymous access enabled in Artifactory.

Docker version

Search with the Docker client is only supported in Docker V1.

Search Using the REST API

If you are using a Docker version below 1.2.0, you can search for images using the Artifactory REST API as follows:

curl -i -uadmin:password "https://artprod.company.com/v1/search?q=ubun"
{
  "num_results" : 1,
  "query" : "ubun",
  "results" : [ {
    "name" : "library/ubuntu",
    "description" : ""
  } ]
}

You can optionally add a docker.description property.

In this case, the description is also used in search, and is displayed in the Docker registry REST API response.

...

  "results" : [ {
    "name" : "library/ubuntu",
    "description" : "Main Linux distribution"
  } ]
...

Deletion and Cleanup

From version 3.5, Artifactory natively supports removal of tags and repositories and complies with the  Docker Hub Spec.

Deletion of Docker tags and repositories automatically cleans up any orphan layers that are left (layers not used by any other tag/repository).

Currently, the Docker client does not support DELETE commands, but deletion can be triggered manually using cURL. Here are some examples:

Removing repositories and tags
//Removing the "jfrog/ubuntu" repository
 curl -uadmin:password -X DELETE "https://artprod.company.com/v1/repositories/jfrog/ubuntu"
 
//Removing the "12.04" tag from the "jfrog/ubuntu" repository
 curl -uadmin:password -X DELETE "https://artprod.company.com/v1/repositories/jfrog/ubuntu/tags/12.04" 

You can also remove tags and repositories through the UI:

Empty Directories

Any empty directories that are left following removal of a repository or tag will automatically be removed during the next folder pruning job (which occurs every 5 minutes by default).

Promoting Docker Images with V1

Promoting Docker images with Docker V1 is done in exactly the same way as when Promoting Images with Docker V2


Migrating a V1 repository to V2

We recommend using Docker V2 repositories when possible (provided your Docker client is version 1.6 and above).

If you have an existing Docker V1 repository, you can migrate it's content into a V2 repository using the following endpoint with cURL:

POST api/docker/<repoKey>/v1/migrate
{ 
    "targetRepo" : "<targetRepo>",
    "dockerRepository" : "<dockerRepository>",
    "tag" : "<tag>"
}

where:

<repoKey>

Source repository key (For example, docker-local as used in this page)

<targetRepo>

The target repository to migrate to (For example, docker-local2 as used in this page)

<dockerRepository>

An optional docker repository name to migrate, if null - the entire source repository will be migrated. Default: ""

<tag>

An optional tag name to promote, if null - the entire docker repository will be promoted. Default: ""

 

An example for migrating the docker image "jfrog/ubuntu" with all of it's tags from docker-local to docker-local2 using cURL would be:

curl -i -uadmin:password -X POST "http://localhost:8080/artifactory/api/docker/docker-local/v1/migrate" -H "Content-Type: application/json" -d
'{"tagetRepo":"docker-local2","dockerRepository":"jfrog/ubuntu"}'

Using Docker in Artifactory Online

Due to limitations of the Docker client, in Artifactory Online there is a special configuration for each server with a sub-domain which depends on the Docker Registry API version you are using.

Docker Registry V1 API

You need to create a new Docker enabled local repository named docker-local.

Then, use the following address when working with the Docker client: "${account_name}.artifactoryonline.com"



Docker Registry V2 API

You need to create a new Docker V2 enabled local repository named dockerv2-local.

Then, use the following address when working with the Docker client: "${account_name}-docker-dockerv2-local.artifactoryonline.com"