Docker Registry

Synapse Docker Registry

Docker is a tool for creating, running, and managing lightweight virtual machines. These virtual machines make it possible to distribute executable environments with all of the dependencies that can easily be run by others. These Docker images can then be stored and distributed on a Docker registry, a collection of these images. There are a number of open registries on the web, and Synapse hosts a private registry, freely available to our users, which will allow users to create software on a per project basis which can be easily shared across Synapse. Learn more about Docker and Docker registry.

Synapse users interact with the Synapse Docker registry using the standard Docker client. In Synapse, Docker containers are represented as versioned ‘repositories’ under the ‘Docker’ tab. As with Files and Tables, Repositories are organized by project and inherit the access controls from the project.

Creating a new Docker image

Let’s begin by creating a custom Docker image. Users can choose to either modify an existing Docker image or build a Docker image from a Dockerfile. Docker images must be tagged with ‘’ to allow images to be saved.

Tagging an existing Docker image to save onto the Synapse registry

docker pull ubuntu

To tag an existing Docker image, users can use the IMAGE ID or the repo name. The IMAGE ID can be found by doing:

docker images
#ubuntu	latest	f8d79ba03c00	6 days ago	126.4 MB

Tag the Docker image:

docker tag f8d79ba03c00 
docker tag ubuntu:latest 

You can also choose to not tag your image with an explicit tag, which will by default tag it with latest.

docker tag f8d79ba03c00

Build your own image from a Dockerfile When building a Docker image from a Dockerfile simply add a -t to the docker build command with the correct Synapse Docker registry tag.

docker build -t path/to/dockerfile

Learn more about building docker images.

Storing Docker images in the Synapse Docker Registry

To store Docker images, use the docker push command. To push to the Synapse Docker Registry, users must be logged into the registry:

docker login -u <synapse username> -p <synapse password>

After logging in, view your images and decide which ones to push into the registry.

docker images
#REPOSITORY                                 TAG                 IMAGE ID            CREATED             SIZE   version1            f8d79ba03c00        6 days ago          126.4 MB
#ubuntu                                     latest              f8d79ba03c00        6 days ago          126.4 MB	latest	df323sdf123d	2 days ago	200.3 MB
docker push
docker push

Using Docker images stored in the Synapse Docker Registry

To access the Docker images stored in Synapse, simply use the docker pull command.

synapse logo Tip: By default, if you do not specify a tag, it will attach latest as the tag. If you specified a tag on your repository, be sure to pull the repository with the tag.
docker pull

Docker tags can be assigned to later commits. If you want to be explicit about the version of an image then instead of referencing a tag you can reference a digest:

docker pull

where the digest for a commit is printed to the command line after a successful Docker push. The Synapse web portal displays current digests for a repository’s tags on the repository’s Synapse page.

synapse logo Note: You can add external repositories, i.e. repositories that live in other registries like DockerHub and For these repositories there is no tight integration (Synapse doesn't contact these external registries) but it allows you to list Docker repositories that are relevant to the project but are not within Synapse.

Need More Help!

Try posting a question to our Forum.

Let us know what was unclear or what has not been covered. Reader feedback is key to making the documentation better, so please let us know or open an issue in our Github repository (Sage-Bionetworks/synapseDocs).

2018 Sage Bionetworks Contact us Creative Commons License