Skip to end of metadata
Go to start of metadata

Overview

Set up a secure private Docker registry in minutes to manage all your Docker images while exercising fine-grained access control.JFrog Container Registry 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 a remote Docker registry such as Docker Hub.

Multiple Docker Registries
JFrog Container Registry lets you create 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

JFrog Container Registry supports the relevant calls of the Docker Registry API so that you can transparently use the Docker client to access images through JFrog Container Registry.

Secure private Docker Registry with Fine-grained Access Control
Local Docker Repositories are where you store internal Docker images for distribution across your organization. With the fine-grained access control provided by built-in security features, JFrog Container Registry offers secure Docker push and pull with local Docker repositories as fully functional, secure, private Docker registries.

Consistent and reliable access to remote images
Remote Docker Repositories in JFrog Container Registry proxy external registries such as Docker Hub, or a Docker repository in another JFrog Container Registry instance, and cache downloaded images. As a result, overall networking is reduced, and access to images on these remote resources is faster, consistent and reliable.

Confidently Promoting Images to Production
JFrog Container Registry lets you promote Docker images, as immutable, stable binaries, through the quality gates all the way to production.

Smart Search
Using JFrog Container Registry's Package Search, find your images in the most natural way for Docker using the image name, tag or digest.

Registries and Repositories

Both JFrog Container Registry 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

JFrog Container Registry 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 JFrog Container Registry places no limitation on the number of repositories you may create, you can manage any number of Docker registries in JFrog Container Registry.



Getting Started With JFrog Container Registry as a Docker Registry

There are two main ways to get started using Docker with JFrog Container Registry:

  • JFrog Container Registry Cloud account
  • JFrog Container Registry On-Prem

For more details, please refer to Getting Started with JFrog Container Registry as a Docker Registry.


Configuring Docker Repositories

JFrog Container Registry supports three types of repositories when working with Docker:

  • Local repositories are a place for your internal Docker images. Through JFrog Container Registry's security capabilities, these are secure private Docker registries.
  • Remote repositories are used to proxy remote Docker registries 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 his users knowing, and continue to work with the same end point.

**Make sure to go to the Advanced tab of each repository and set the Registry Port if you are using the Port method for Docker. Then, the reverse proxy generator should add a new section in for the specified port.

Do not use underscores when naming Docker repositories

Due to a limitation in the Docker client, underscores are not permitted in Docker registry names. Therefore, when naming JFrog Container Registry Docker repositories, you should not use an underscore. For example, the Docker client will not be able to communicate with a repository named test_docker_repo, however it will work with a repository named test.docker.repo.


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.

To define a local Docker repository, follow the steps below:

  1. Create a new Local Repositories and set Docker as the Package Type. 
  2. Set the Repository Key, and in the Docker Settings section, select V2 as the Docker API version.

  3. 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.

 New local Docker repository

Remote Docker Repositories

With Docker, you can proxy a remote Docker registry through remote repositories. A Remote Repository defined in JFrog Container Registry serves as a caching proxy for a registry managed at a remote URL such as https://registry-1.docker.io/ (which is the Docker Hub), or even a Docker repository managed at a remote site by another instance of JFrog Container Registry.

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. Create a new Remote Repository and set Docker as the Package Type.
  2. Set the Repository Key value, and specify the URL to the remote registry in the URL field

    New remote Docker repository

    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 JFrog Container Registry, the repository URL must be prefixed with api/docker in the path.

For Example:

http://my-remote-site:8081/jfrogcontainerregistry/api/docker/<repository key>


Virtual Docker Repositories

JFrog Container Registry supports virtual Docker Repositories. A Virtual Repository defined in JFrog Container Registry 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:

  1. Create a new Virtual Repository and set Docker as the Package Type.
  2. Set the Repository Key value.

  3. Select the underlying local and remote Docker repositories to include under the Repositories section.
  4. 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.

New Docker Virtual Repository

Resolve Latest Docker Image

To set your virtual Docker repository to pull Docker images according to their modification time, enable Resolve Docker Tags By Latest Timestamp. This is useful in scenarios where two or more aggregated repositories contain the same tag name. For example, busybox:1.1.

When enabled, instead of fetching the image that is positioned higher in the resolution order in the virtual repository, JFrog Container Registry will return the Docker image last deployed to one of the aggregated repositories in the Virtual repository. JFrog Container Registry will first try to fetch the tag from the Local repositories according to the modification time, if not found, it will continue to try to fetch the image from the Remote repositories according to the resolution order.

This functionality is useful for multi-site environments where you create the same image on two different instances. 


Reverse Proxy Settings

JFrog Container Registry supports access to Docker registries either through a reverse proxy (using the Subdomain method or through port bindings), or using direct access.

When accessing through a reverse proxy, if you are using the JFrog Container Registry Reverse Proxy configuration generator you can configure a Docker repository's reverse proxy settings under the Advanced settings tab.

For details, please refer to Docker Reverse Proxy Settings.


Promoting Docker Images

JFrog Container Registry supports promoting Docker images from one Docker repository in JFrog Container Registry 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:

POST api/docker/<repoKey>/v2/promote
{ 
    "targetRepo" : "<targetRepo>",  
    "dockerRepository" : "<dockerRepository>",  
    "tag" : "<tag>", 
	"targetTag" : "<tag>",
    "copy": <true | false>
}

where:

repoKeySource repository key
targetRepoThe target repository to move or copy
dockerRepositoryThe docker repository name to promote
tagAn optional tag name to promote, if null - the entire docker repository will be promoted. Default: "latest" 
targetTagThe new tag that the image should have after being promoted if you want to
copyWhen 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-local to docker-prod using cURL would be:

curl -i -uadmin:password -X POST "https://artprod.company.com/v2/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 JFrog Container Registry, you would execute this command as follows:

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


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:


curl -i -uadmin:password -X POST "https://artprod.company.com/v2/promote" -H "Content-Type: application/json" -d '{"targetRepo":"docker-prod","dockerRepository":"jfrog/ubuntu", "tag" : "4.9.0", "targetTag" : "latest"}'



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 JFrog Container Registry.

The Docker Info tab presents three sections: Tag Info, Docker Tag Visualization, and Labels.

Tag Info

Presents basic details about the selected tag.

Docker Tag Info

Title
The Docker tag name.
Digest

The tag's SHA 256 digest.

Total Size
The total size of the image
Label Count

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 docker history.

You can select any layer of the image to view the following properties:

SymbolProperty
The layer ID
The layer size
The timestamp when the layer was created
The command that created the layer

Docker Tag Visualization

Labels

This section displays the labels attached to the image.

Docker Labels

JFrog Container Registry 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.

Docker Label Properties


Searching for Docker Images

You can search for Docker images by their name, tag or image digest using JFrog Container Registry's Package Search or through the REST API.

Docker Search


Listing Docker Images

JFrog Container Registry supports the following REST API endpoints related to Docker registries:

  • List Docker Image provides a list of Docker images in the specified JFrog Container Registry Docker registry. This endpoint mimics the Docker _catalog REST API.
  • List Docker Tags provides a list of tags for the specified Docker image. 

JFrog Container Registry also supports pagination for this endpoint.

To enable fetch from cache using the List Docker Repositories and the List Docker Tag rest APIs, set the jfrogcontainerregistry.docker.catalogs.tags.fallback.fetch.remote.cache system property to true (default false) in the jfrogcontainerregistrysystem.properties file:

## Enable fetch from cache in Docker repositories
#jfrogcontainerregistry.docker.catalogs.tags.fallback.fetch.remote.cache=true

JFrog Container Registry needs to be restarted for this change to take effect.


Pushing Images to Bintray

Through JFrog Container Registry's close integration with JFrog Bintray, you can push Docker images from your JFrog Container Registry 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, use the Distribution Repository.


Deletion and Cleanup

JFrog Container Registry 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. To delete an entire Docker repository using cURL, execute the following command:

curl -u<user:password> -X DELETE "<jfrogcontainerregistry URL>/jfrogcontainerregistry/<Docker v2 repository name>/<image namespace>"

Or for a specific tag version:

curl -u<user:password> -X DELETE "<jfrogcontainerregistry URL>/jfrogcontainerregistry/<Docker v2 repository name>/<image namespace>/<tag>"


For example, to remove the latest tag of an Ubuntu repository:

//Removing the latest tag from the "jfrog/ubuntu" repository
curl -uadmin:password -X DELETE "https://artprod.company.com/jfrogcontainerregistry/dockerv2-local/jfrog/ubuntu/latest"

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).

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 Repositories configuration to limit the number of unique tags. 


Docker Build Information

You may store exhaustive build information in JFrog Container Registry by running your Docker builds with JFrog CLI. 

JFrog CLI collects build-info from your build agents and then publishes it to JFrog Container Registry. Once published, the build info can be viewed in the Inspecting Builds under Builds.

For more details on Docker build integration using JFrog CLI, please refer to Building Docker Images in the JFrog CLI User Guide.


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.

For details, please refer to Migrating a V1 repository to V2 under the Using Docker V1 documentation.

Using Docker V1?

This document shows how to use JFrog Container Registry with the Docker V2 . If you are using the Docker V1, please refer to Using Docker V1.