Getting Started with Artifactory as a Docker Registry

Overview

There are these main ways you can use Docker with Artifactory, including:

Artifactory Cloud

The easiest way is with an Artifactory Cloud account. In this mode, since Artifactory is a hosted service, you do not need to set up a reverse proxy and can create your Docker repositories and start pushing and pulling Docker images. Getting Started with Artifactory Cloud >

Artifactory Self-hosted

Set up your self-hosted installation of Artifactory Pro to work with Docker. The Docker client requires a different hostname for each registry. Artifactory supports this whether you are using a reverse proxy or not. Get Started with Artifactory Pro Self-hosted >

Artifactory Deployment Best Practices

JFrog recommended best practice is to use EC2 or container based deployments (EKS) for deploying Artifactory. AWS Fargate is not recommended at this time.

Integration Benefits Docker Registry

Getting Started with Artifactory Cloud

Using Docker repositories with Artifactory Cloud is quick and easy. With Artifactory Cloud, you are using Artifactory as a hosted service and there is no need to configure Artifactory with a reverse proxy.

The example at the end of this section shows a complete process of creating a Docker repository, logging in, pulling an image and pushing an image.

Using Docker Client with Artifactory Cloud

To use the Docker client with one of your Artifactory Cloud Docker repositories, you can use the native Docker client to login to each Docker repository, pull, and push images.

Log in to your repository use the following command with your Artifactory Cloud credentials.
```
docker login ${server-name}.jfrog.io
```

Pull an image using the following command.

docker pull ${server-name}.jfrog.io/{repo-name}/<image name>

Push an image by first tagging it and then using the push command.

docker tag <image name> ${server-name}.jfrog.io/{repo-name}/<image name>
docker push ${server-name}.jfrog.io/{repo-name}/<image name>

Test Your Setup

The following example demonstrates the following scenario:

Pulling the hello-world Docker image
Logging into your virtual Docker repository
Retagging the hello-world image, and then pushing it into your virtual Docker repository

Note

In this example, the Artifactory Cloud server is named acme.

Start by creating a virtual Docker repository called dockerv2-virtual.
Pull the hello-world image
```
docker pull hello-world
```

docker login acme-dockerv2-virtual.jfrog.io

Tag the hello-world image

docker tag hello-world acme-dockerv2-virtual.jfrog.io/hello-world

Push the tagged hello-world image to dockerv2-virtual

docker push acme-dockerv2-virtual.jfrog.io/hello-world

Getting Started with Artifactory Pro Self-hosted

The Docker client has the following two limitations:

You cannot use a context path when providing the registry path (e.g localhost:8082/artifactory is not valid)
Docker will only send basic HTTP authentication when working against an HTTPS host or when using the insecure registry flag

Artifactory offers solutions to these limitations allowing you to create and use any number of Docker registries.

Using a reverse proxy When used, a reverse proxy, maps Docker commands to one of the multiple Docker registries in Artifactory
Without a reverse proxy From version 5.8, Artifactory supports using Docker without the use of a reverse proxy allowing you to create and use multiple Docker registries in Artifactory out-of-the-box.

Using a Reverse Proxy

When using Artifactory with a reverse proxy, you need to map Docker commands to Docker registries in Artifactory using either the subdomain method, ports method or repository path method.

Testing or evaluating?

If you are currently only testing or evaluating using Artifactory with Docker, we recommend running artifactory as a Docker container which is easily installed and comes with a proxy server and Docker registries pre-configured out-of-the-box. You can be up and running in minutes.

With the ports method, a port number is mapped to each Artifactory Docker registry. While this is an easy way to get started, you will need to modify your reverse proxy configuration and add a new mapping for each new Docker registry you define in Artifactory. In addition, firewalls and other restrictions by your IT department may restrict port numbers making the ports method not feasible.

With the subdomain method, you only need to configure your reverse proxy once, and from then on, the mapping from Docker commands to Docker registries in Artifactory is dynamic and requires no further modification of your reverse proxy configuration.

The repository path method allows a single point of entry (URL) to access different repositories. This is done by embedding the name of the repository being accessed into the image path.

If a wildcard certificate is available, we recommend the subdomain method since it will only require a one time effort and follows Docker convention more closely.

The Subdomain Method

Getting started with Docker and your self-hosted Artifactory Pro installation using the subdomain method involves four basic steps:

Configuring Artifactory

To configure Artifactory and your reverse proxy using the subdomain method, carry out the following steps:

Make sure Artifactory is up and running, and is activated with a valid license.Installing Artifactory
Create your virtual Docker repository (as well as a local and remote Docker repository that it should aggregate). In our example below we will use a repository named docker-virtual.
Make sure you have a reverse proxy server up and running.
Obtain a wildcard SSL certificate or use a wildcard self-signed certificate. To create a self-signed certificate, you can follow these instructions for Ubuntu.
Note
Make sure your certificate matches the Artifactory hostname used in your reverse proxy configuration. In our example below we will use art.local.

Configuring Your Reverse Proxy

Artifactory's can generate your complete reverse proxy configuration file for supported servers.

Go to Reverse Proxy Configuration Generator and fill in the fields according to how your reverse proxy is set up while making sure to:

Use the correct Artifactory hostname in the Public Server Name field (in our example this will be art.local)
Select Subdomain as the Reverse Proxy Method under Docker Reverse Proxy Settings.

Nginx

Copy the code snippet generated by the configuration generator into your artifactory-nginx.conf file, and place it in your /etc/nginx/sites-available directory.

Create the following symbolic link.

sudo ln -s /etc/nginx/sites-available/artifactory-nginx.conf /etc/nginx/sites-enabled/artifactory-nginx.conf

Apache HTTPD

Copy the code snippet generated by the configuration generator into your artifactory-apache.conf file and place it in your /etc/apache2/sites-available directory.

Create the following symbolic link:

sudo ln -s /etc/apache2/sites-available/artifactory-apache.conf /etc/apache2/sites-enabled/artifactory-apache.conf

Note

The httpd.conf header file should be tuned to work correctly using these values to avoid errors:

# Apache libraries location (should be tuned)
Define APACHE_LIB_DIR /usr/lib/apache2/modules      <---- Input fied in UI could be great

# Apache Logs (default : beside other Artifactory logs)
Define APACHE_LOG_DIR /[TheArtifactoryHome]/logs         <---- ErrorLog/CustomLog could be uncommented & Input fied in UI could be great

LoadModule proxy_module  ${APACHE_LIB_DIR}/mod_proxy.so
LoadModule rewrite_module  ${APACHE_LIB_DIR}/mod_rewrite.so
LoadModule proxy_ajp_module  ${APACHE_LIB_DIR}/mod_proxy_ajp.so
LoadModule proxy_http_module ${APACHE_LIB_DIR}/mod_proxy_http.so
LoadModule ssl_module  ${APACHE_LIB_DIR}/mod_ssl.so       <---- Only if HTTPS used

Listen 443        <---- Only if HTTPS used
Listen XXX        <--- All port used as Docker registry

Configuring Your Docker Client

To configure your Docker client, carry out the following steps

Add the following to your DNS or to the client's /etc/hosts file:
```
<ip-address> docker-virtual.art.local 
```
Since the certificate is self-signed, you need to import it to your Docker certificate trust store as described in the Docker documentation. Alternatively, you can configure the Docker client to work with an insecure registry as described in the Docker documentation.
Restart your Docker daemon/engine to apply the insecure registry flag (if self-signed certificate is imported, you do not need to restart the Docker daemon/engine).

Test Your Setup

To verify your reverse proxy is configured correctly, run the following command making sure that the return code is 200:

curl -I -k -v https://<artifactory url>/api/system/ping

Run the following commands to ensure your proxy configuration is functional and can communicate with Artifactory:

Pull the "hello-world" image
```
docker pull hello-world
```
Login to repository docker-virtual
```
docker login docker-virtual.art.local
```

Tag the "hello-world" image

docker tag hello-world docker-virtual.art.local/hello-world

Push the tagged "hello-world" image to docker-virtual
```
docker push docker-virtual.art.local/hello-world
```

The Repository Path Method

Getting started with Docker and your self-hosted Artifactory Pro installation using the path method involves four basic steps:

Configuring Artifactory

To configure Artifactory and your reverse proxy using the path method, carry out the following steps:

Make sure Artifactory is up and running, and is activated with a valid license.Installing Artifactory
Create your Virtual Docker Repositories (as well as a local and remote Docker repository that it should aggregate). In our example below we will use a repository named docker-virtual.
Make sure you have a reverse proxy server up and running.
Obtain a valid SSL certificate or use a self-signed certificate. To create a self-signed certificate, you can follow these instructions for Ubuntu.
Note
Make sure your certificate matches the Artifactory hostname used in your reverse proxy configuration. In our example below we will use art.local.

Configuring your reverse proxy

Artifactory's can generate your complete reverse proxy configuration file for supported servers.

Go to Reverse Proxy Configuration Generator and fill in the fields in according to how your reverse proxy is set up while making sure to:

Use the correct Artifactory hostname in the Public Server Name field (in our example this will be art.local)
Select Repository Path as the Reverse Proxy Method under Docker Reverse Proxy Settings.

NginxCopy the code snippet generated by the configuration generator into your artifactory-nginx.conf file, and place it in your /etc/nginx/sites-available directory.

Create the following symbolic link.

sudo ln -s /etc/nginx/sites-available/artifactory-nginx.conf /etc/nginx/sites-enabled/artifactory-nginx.conf

Apache HTTPD

Copy the code snippet generated by the configuration generator into your artifactory-apache.conf file and place it in your /etc/apache2/sites-available directory.

Create the following symbolic link:

sudo ln -s /etc/apache2/sites-available/artifactory-apache.conf /etc/apache2/sites-enabled/artifactory-apache.conf

Configuring Your Docker Client

To configure your Docker client, carry out the following steps

Add the following to your DNS or to the client's /etc/hosts file:
```
<ip-address> art.local 
```
Since the certificate is self-signed, you need to import it to your Docker certificate trust store as described in the Docker documentation. Alternatively, you can configure the Docker client to work with an insecure registry as described in the Docker documentation.
Restart your Docker daemon/engine to apply the insecure registry flag (if self-signed certificate is imported, you do not need to restart the Docker daemon/engine).

Test Your Setup

To verify your reverse proxy is configured correctly, run the following command making sure that the return code is 200:

curl -I -k -v https://<artifactory url>/api/system/ping

Run the following commands to ensure your proxy configuration is functional and can communicate with Artifactory:

Pull the "hello-world" image
```
docker pull hello-world
```
Login to repository docker-virtual
```
docker login art.local
```

Tag the "hello-world" image

docker tag hello-world art.local/docker-virtual/hello-world

Push the tagged "hello-world" image to docker-virtual
```
docker push art.local/docker-virtual/hello-world
```

The Ports Method

Getting started with Docker and your self-hosted Artifactory Pro installation using the ports method involves two basic steps:

Configuring Artifactory and Your Reverse Proxy

To configure Artifactory and your reverse proxy using the ports method, carry out the following steps:

Make sure Artifactory is up and running, and is activated with a valid license.Installing Artifactory
Create your Virtual Docker Registry (as well as a local and remote Docker repository that it should aggregate). In our example below we will use a repository named docker-virtual.
Make sure you have a reverse proxy server up and running.
Obtain an SSL certificate or use a Self-Signed certificate that can be generated following this example.
Note
Make sure your certificate matches the Artifactory hostname used in your reverse proxy configuration. In our example below we will use art.local.

Configure your reverse proxy. Artifactory's Reverse Proxy Configuration Generator can generate your complete reverse proxy configuration file for supported servers. All you need to do is fill in the fields in according to how your reverse proxy is set up while making sure to:

Use the correct Artifactory hostname in the Public Server Name field
Select Ports as the Reverse Proxy Method under Docker Reverse Proxy Settings. In the example below, we will use port 5001 to bind repository docker-virtual .

NGINX

For Artifactory to work with Docker, the preferred web server is NGINX v1.3.9 and above. First, you need to create a self-signed certificate for NGINX as described here for Ubuntu. Then use Artifactory's Reverse Proxy Configuration Generator to generate the configuration code snippet for you. Copy the code snippet into your artifactory-nginx.conf file and place it in your /etc/nginx/sites-available directory. Finally, create the following symbolic link:

sudo ln -s /etc/nginx/sites-available/artifactory-nginx.conf /etc/nginx/sites-enabled/artifactory-nginx.conf

Apache HTTPD

Install Apache HTTP server as a reverse proxy and then install the required modules. Create the following symbolic link:

sudo ln -s /etc/apache2/mods-available/slotmem_shm.load /etc/apache2/mods-enabled/slotmem_shm.load

Similarly, create corresponding symbolic links for:

headers
proxy_balancer
proxy_load
proxy_http
proxy_connect
proxy_html
rewrite.load
ssl.load
lbmethod_byrequests.load

Then use Artifactory's Reverse Proxy Configuration Generator to generate the configuration code snippet for you.

Copy the code snippet into your artifactory.conf file and place it in your /etc/apache2/sites-available directory.

HAProxy

First, you need to create a self-signed certificate for HAProxy as described here for Ubuntu. Then, copy the code snippet below into your /etc/haproxy/haproxy.cfg file. After editing the file as described in the snippet, you can test your configuration using the following command:

haproxy -f /etc/haproxy/haproxy.cfg -c

HAProxy v1.5 Configuration Expand source

# haproxy server configuration
# version 1.0
# History
# ---------------------------------------------------------------------------
# Features enabled by this configuration
# HA configuration
# port 80, 443  Artifactory GUI/API
#
# This uses ports to distinguish artifactory docker repositories
# port 443  docker-virtual (v2) docker v1 is redirected to docker-dev-local.
# port 5001 docker-prod-local (v1); docker-prod-local2 (v2)
# port 5002 docker-dev-local (v1); docker-dev-local2 (v2)
#
# Edit this file with required information enclosed in <...>
# 1. certificate and key
# 2. artifactory-host
# 3  replace the port numbers if needed
# ----------------------------------------------------------------------------
global
        log 127.0.0.1   local0
        chroot /var/lib/haproxy
        maxconn 4096
        user haproxy
        group haproxy
        daemon
        tune.ssl.default-dh-param 2048
        stats socket /run/haproxy/admin.sock mode 660 level admin
defaults
        log     global
        mode    http
        option  httplog
        option  dontlognull
        option  redispatch
        option  forwardfor
        option  http-server-close
        maxconn 4000
        timeout connect 5000
        timeout client 50000
        timeout server 50000
        errorfile 400 /etc/haproxy/errors/400.http
        errorfile 403 /etc/haproxy/errors/403.http
        errorfile 408 /etc/haproxy/errors/408.http
        errorfile 500 /etc/haproxy/errors/500.http
        errorfile 502 /etc/haproxy/errors/502.http
        errorfile 503 /etc/haproxy/errors/503.http
        errorfile 504 /etc/haproxy/errors/504.http 
frontend normal
         bind *:80
         bind *:443 ssl crt </etc/ssl/certs/server.bundle.pem>
         mode http
         option forwardfor
         reqirep ^([^\ :]*)\ /v2(.*$) \1\ /artifactory/api/docker/docker-virtual/v2\2
         reqadd X-Forwarded-Proto:\ https if { ssl_fc }
         option forwardfor header X-Real-IP
         default_backend normal

# if only need to access the docker-dev-local2 then skip this section. Docker-virtual can be configured to deploy to docker-dev-local2 frontend dockerhub
         bind *:5000 ssl crt </etc/ssl/certs/server.bundle.pem>
         mode http
         option forwardfor
         option forwardfor header X-Real-IP
         reqirep ^([^\ :]*)\ /v2(.*$) \1\ /artifactory/api/docker/docker-remote/v2\2
         reqadd X-Forwarded-Proto:\ https if { ssl_fc }
         default_backend normal

# if only need to access the docker-dev-local2 then skip this section. Docker-virtual can be configured to deploy to docker-dev-local2 frontend dockerprod
         bind *:5001 ssl crt </etc/ssl/certs/server.bundle.pem>
         mode http
         option forwardfor
         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
         reqadd X-Forwarded-Proto:\ https if { ssl_fc }
         default_backend normal
 
# if only need to access the docker-dev-local2 then skip this section. Docker-virtual can be configured to deploy to docker-dev-local2 frontend dockerdev
         bind *:5002 ssl crt </etc/ssl/certs/server.bundle.pem>
         mode http
         option forwardfor
         option forwardfor header X-Real-IP
             reqirep ^([^\ :]*)\ /v1(.*$) \1\ /artifactory/api/docker/docker-dev-local/v1\2
             reqirep ^([^\ :]*)\ /v2(.*$) \1\ /artifactory/api/docker/docker-dev-local2/v2\2
         reqadd X-Forwarded-Proto:\ https if { ssl_fc }
         default_backend normal
 
# Artifactory Non HA Configuration
# i.e server artifactory 198.168.1.206:8082
#
backend normal 
         mode http
         server <artifactory-host> <artifactory-host ip address>:<artifactory-host port>
 
#
# Artifactory HA Configuration
# Using default failover interval - rise = 2; fall =3 3; interval - 2 seconds
# backend normal
#        mode http
#        balance roundrobin
#        option httpchk OPTIONS /
#        option forwardfor
#        option http-server-close
#        appsession JSESSIONID len 52 timeout 3h
#        server <artifactory-host-ha1> <artifactory-host ip address>:<artifactory-host port> 
#                server <artifactory-host-ha2> <artifactory-host ip address>:<artifactory-host port>

Configuring Your Docker Client

To configure your Docker client, carry out the following steps

Add the following to your DNS or to the client's /etc/hosts file:
```
<ip-address> art.local 
```
Since the certificate is self-signed, you need to import it to your Docker certificate trust store as described in the Docker documentation. Alternatively, you can configure the Docker client to work with an insecure registry by adding the following line to your /etc/default/docker file (you may need to create the file if it does not already exist):
```
DOCKER_OPTS="$DOCKER_OPTS --insecure-registry art.local:5001"
```
Restart your Docker engine.

Test Your Setup

To verify your reverse proxy is configured correctly, run the following command:

// Make sure the following results in return code 200
curl -I -k -v https://<artifactory url>/api/system/ping

Run the following commands to ensure your proxy configuration is functional and can communicate with Artifactory. In this example, we will pull down a Docker image, tag it and then deploy it to our docker-virtual repository that is bound to port 5001:

// Pull the "hello-world" image
docker pull hello-world
 
// Login to repository docker-virtual
docker login art-local:5001
 
// Tag the "hello-world" image
docker tag hello-world art-local:5001/hello-world
 
// Push the tagged "hello-world" image to docker-virtual
docker push art-local:5001/hello-world

Testing With a Self-signed Certificate

Since the certificate is self-signed, you need to import it to your Docker certificate trust store as described in the Docker documentation. Alternatively, you can configure the Docker client to work with an insecure registry as described in the Docker documentation.
Restart your Docker daemon/engine to apply the insecure registry flag (if self-signed certificate is imported, you do not need to restart the Docker daemon/engine).
Running $docker info will list the Insecure registries that have been applied under the Insecure Registries entry.
Use the steps above to interact with the Artifactory Docker Registry

Without a Reverse Proxy

Previously, Artifactory supported the Ports and Subdomain methods described above when using a reverse proxy. From version 5.8. Artifactory introduces a new method referred to as the "Repository Path" method since it uses the Docker repository path prefix (<REPOSITORY_KEY/IMAGE>) to access a specific Artifactory Docker registry from the Docker client. Note that you may still have a reverse proxy configured for Artifactory for other reasons, however, when configured to use Repository Path method, requests to Docker registries in Artifactory will be handled by Artifactory's embedded Tomcat instead of the reverse proxy.

Docker API v2 required

You can only use the Repository Path method with Artifactory Docker registries configured for Docker API v2.

Sub-domain method is recommended for production

We recommend using the Sub-domain method for Artifactory Docker registries in production systems because this method allows you to add wildcard SSL certificates on the reverse proxy for secure access to the Docker registry.

While you can add SSL certificates at the Tomcat level, this is not a recommended practice because the process of validation against the certificate is very resource intensive on memory and CPU.

The Repository Path method is more suitable when secure access is not required.

Configuring Artifactory

To configure Artifactory to use the Repository Path method, carry out the following steps:

Make sure Artifactory is up and running, and is activated with a valid license.Installing Artifactory
Create your virtual Docker repository (as well as a local and remote Docker repository that it should aggregate). In our example below we will use a repository named docker-virtual.
Go to the HTTP Settings page from the Administration module under Artifactory | General | HTTP Settings.In the Docker Settings panel, select Repository Path as the Docker Access Method.
In the Reverse Proxy Settings panel select Embedded Tomcat as theServer Provider (which indicates you're not using a reverse proxy).
You must use Embedded Tomcat
You can only use Artifactory as a Docker registry without a reverse proxy by using the internal embedded Tomcat.

Configuring Your Docker Client

Using the Repository Path method, you can work with Artifactory as a Docker registry without a reverse proxy on an insecure connection (i.e. only HTTP is supported, not HTTPS). You need to configure the Docker client to work with an insecure registry as described in the Docker documentation.

Restart your Docker daemon/engine to apply the insecure registry flag (if self-signed certificate is imported, you do not need to restart the Docker daemon/engine). Running $docker info will list the Insecure registries that have been applied under the Insecure Registries entry.

Test Your Setup

Don't use localhost or 127.0.0.1 or "/artifactory"

Due to a limitation in the Docker client, you cannot access an Artifactory Docker registry as localhost or 127.0.0.1. If you need to access a local installation of Artifactory, make sure to specify its full IP address.

In addition, when specifying Artifactory's URL, you should omit the /artifactory suffix normally used.

For example, if your local machine's IP address is 10.1.16.114, then you must specify your Artifactory URL as http:// 10.1.16.114:8082 (using http://localhost :8082 will not work).

The code snippets below assume you have a virtual Docker repository named docker-virtual in an Artifactory installation at IP 10.1.16.114.

First, you should verify that your Docker client can access Artifactory by run the following command. Making sure that the return code is 200:

curl -I -k -v http://10.1.16.114:8082/artifactory/api/system/ping

Now you can proceed to test your Docker registry.

docker login -u admin -p password 10.1.16.114:8082

Pull the hello-world image from the docker-virtual repository

docker pull 10.1.16.114:8082/docker-virtual/hello-world:latest

Tag a Docker image

docker tag 10.1.16.114:8082/docker-virtual/hello-world:latest 10.1.16.114:8082/docker-virtual/<tag_name>

Push the tagged image to docker-virtual

docker push 10.1.16.114:8082/docker-virtual/<tag_name>

Overview

Artifactory Cloud

Artifactory Self-hosted

Artifactory Deployment Best Practices

Getting Started with Artifactory Cloud

Using Docker Client with Artifactory Cloud

Test Your Setup

Note

Getting Started with Artifactory Pro Self-hosted

Using a Reverse Proxy

Testing or evaluating?

The Subdomain Method

Note

Nginx

Apache HTTPD

Note

Configuring Your Docker Client

Test Your Setup

The Repository Path Method

Note

The Ports Method

Note

Without a Reverse Proxy

Docker API v2 required

Sub-domain method is recommended for production

Configuring Artifactory

You must use Embedded Tomcat

Configuring Your Docker Client

Test Your Setup

Don't use localhost or 127.0.0.1 or "/artifactory"