Using Artifactory 5.x ?
JFrog Artifactory 5.x User Guide
Have a question? Want to report an issue? Contact JFrog support
Set up a secure private Docker registry in minutes to manage all your Docker images while exercising fine-grained access control. Artifactory places no limitations and lets you set up any number of Docker registries, through the use of local, remote and virtual Docker repositories, and works transparently with the Docker client to manage all your Docker images, whether created internally or downloaded from remote Docker resources such as Docker Hub.
Multiple Docker Registries
Artifactory lets you define as many Docker registries as you wish. This enables you to manage each project in a distinct registry and exercise better access control to your Docker images.
Use Docker Naturally
Registries and Repositories
Both Artifactory and Docker use the term "repository", but each uses it in a different way.
A Docker repository is a hosted collection of tagged images that, together, create the file system for a container
A Docker registry is a host that stores Docker repositories
An Artifactory repository is a hosted collection of Docker repositories, effectively, a Docker registry in every way, and one that you can access transparently with the Docker client.
Since Artifactory places no limitation on the number of repositories you may create, you can manage any number of Docker registries in Artifactory.
Getting Started With Artifactory as a Docker Registry
There are three main ways to get started using Docker with Artifactory:
- Artifactory SaaS account
- Using Docker Compose (1-minute setup)
- Artifactory On-Prem
For more details, please refer to Getting Started with Docker and Artifactory.
Configuring Docker Repositories
Artifactory supports three types of repositories when working with Docker:
Local repositories are a place for your internal Docker images. Through Artifactory's security capabilities, these are secure private Docker registries.
Remote repositories are used to proxy remote Docker resources such as Docker Hub.
Virtual repositories can aggregate multiple Docker registries thus enabling a single endpoint you can use for both pushing and pulling Docker images. This enables the admin to manage the different Docker registries without their users knowing, and continue to work with the same end point.
Local Docker Repositories
A local Docker repository is where you can deploy and host your internal Docker images. It is, in effect, a Docker registry able to host collections of tagged Docker images which are your Docker Repositories. Once your images are hosted, you can exercise fine-grained access control, and share them across your organization through replication or by being proxied by repositories in other Artifactory instances.
To define a local Docker repository, follow the steps below:
- Create a new Local Repository and set Docker as the Package Type.
Set the Repository Key, and in the Docker Settings section, select V2 as the Docker API version.
Set Max Unique Tags. This specifies the maximum number of unique tags, per repository, that should be stored for a Docker image. Once the number of tags for an image exceeds this number, older tags will be removed. Leaving the field blank (default) means all tags will be stored.
Remote Docker Repositories
With Docker, you can proxy a remote Docker registry through remote repositories. A 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/
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:
- Create a new Remote Repository and set Docker as the Package Type.
Set the Repository Key value, and specify the URL to the remote registry in the URL field
If you are proxying the Docker Hub, use https://registry-1.docker.io/ as the URL, and make sure the Enable Token Authentication checkbox is checked (these are the default settings).
Docker Repository Path and Domain
When accessing a remote 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 using Set Me Up when the repository is selected in the Tree Browser.
For example, if you are using Artifactory standalone or as a local service, you would access your remote Docker repositories using the following URL:
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 as the proxy pass.
Virtual Docker Repositories
From version 4.1, Artifactory supports virtual Docker Repositories. A Virtual Repository defined in Artifactory aggregates images from both local and remote repositories that are included in the virtual repositories.
This allows you to access images that are hosted locally on local Docker repositories, as well as remote images that are proxied by remote Docker repositories, and access all of them from a single URL defined for the virtual repository. Using virtual repositories can be very useful since users will continue to work with the virtual repository while the admin can manage the included repositories, replace the default deployment target and those changes will be transparent to the users.
To define a virtual Docker repository follow the steps below:
- Create a new Virtual Repository and set Docker as the Package Type.
Set the Repository Key value.
- Select the underlying local and remote Docker repositories to include under the Repositories section.
- You can optionally also configure your Default Deployment Repository. This is the repository to which Docker images uploaded to this virtual repository will be routed, and once this is configured, your virtual Docker repository is a fully-fledged Docker registry. Using the default deployment repository, you can set up your virtual repository to wrap a series of repositories that represent the stages of your pipeline, and then promote images from the default deployment repository through the pipeline to production. Any repository that represents a stage in your pipeline within this virtual repository can be configured with permissions for authenticated or unauthenticated (anonymous) access according to your needs.
Reverse Proxy Settings
A reverse proxy is required for Docker. In case you are using the Artifactory Reverse Proxy configuration generator you can configure Docker repository's reverse proxy settings under the Advanced settings tab.
For details, please refer to Docker Reverse Proxy Settings.
Promoting Docker Images
Artifactory supports promoting Docker images from one Docker repository in Artifactory to another.
Promoting is useful when you need to move Docker images through different acceptance and testing stages, for example, from a development repository, through the different gateways all the way to production. Instead of rebuilding the image multiple times using promotion will ensure the image you will have in your production environment is the one built by your CI server and passed all the relevant tests.
Promotion can be triggered using the following endpoint with cURL:the following endpoint with cURL:
|repoKey||Source repository key|
|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: "latest"|
|targetTag||The new tag that the image should have after being promoted if you want to|
|copy||When true, a copy of the image is promoted. When false, the image is moved to the target repository|
An example for promoting the docker image
"jfrog/ubuntu" with all of it's tags from
docker-prod using cURL would be:
Notice that the above example is executed through your reverse proxy. To go directly through Artifactory, you would execute this command as follows:
The following example adds retagging with a specific version of the "jfrog/ubuntu" image (4.9.0) being retagged to "latest" as it gets promoted:
Pushing and Pulling Images
Set Me Up
To get the corresponding
docker push and
docker pull commands for any repository, select it in the Tree Browser and click Set Me Up button.
Browsing Docker Repositories
For general information on how to browse repositories, please refer to Browsing Artifactory.
Presents basic details about the selected tag.
|Title||The Docker tag name.|
The tag's SHA 256 digest.
|Total Size||The total size of the image|
The number of labels attached to this tag.
Click the label count to view the attached labels at the bottom of the screen.
Docker Tag Visualization
This section maps the entire set of commands used to generate the selected tag along with the digest of the corresponding layer. Essentially, you would see the same series of commands using
You can select any layer of the image to view the following properties:
|The layer ID|
|The layer size|
|The timestamp when the layer was created|
|The command that created the layer|
This section displays the labels attached to the image.
Note also, that from version 4.4.0, Artifactory extracts any labels associated with a Docker image and creates corresponding properties on the
manifest.json file which you can use to specify search parameters, this can be used to easily add additional metadata to any image.
Searching for Docker Images
Listing Docker Images
Pushing Images to Bintray
Through Artifactory's close integration with JFrog Bintray, you can push Docker images from your Artifactory Docker Registries directly to Bintray. To enable this, make sure your Bintray credentials are properly configured in your User Profile page.
To push an image to Bintray, select it in the Tree Browser and select Push to Bintray from the Actions menu.
Artifactory will display a dialog letting you select the Bintray repository to which you want to push the image. The package name and tag are derived automatically from the image you are pushing.
In the Bintray Repository field, Artifactory displays the full list of repositories in your Bintray account. Make sure you select a Bintray Docker repository for your image.
For more details, please refer to Push to Bintray.
Deletion and Cleanup
Artifactory natively supports removing 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 as follows.
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).
Limiting Unique Tags
To avoid clutter and bloat in your Docker registries caused by many snapshots being uploaded for an image, set the Max Unique Tags field in the Local Docker Repository configuration to limit the number of unique tags.
Migrating from Docker V1 to Docker V2
If you are still using Docker V1, we strongly recommend upgrading to Docker V2. This requires that you migrate any Docker repositories that were created for Docker V1, and is done with a simple cURL endpoint.
Using Docker V1?
This document shows how to use Artifactory with the Docker V2 . If you are using the Docker V1, please refer to Using Docker V1.
This matrix provides information on features supported as the versions of Artifactory progress.
|Artifactory Version||Docker Client Version||Docker V1 API||Docker V2 API||Remote Repositories*||Virtual Repositories*|
* Supported for Docker V2 API only