Frequently Asked Questions

Portus is an open source authorization service and user interface for your on-premise Docker registry. Portus will add a fine-grained set of permissions on top of your registry in order to make access more secure and controlled. Moreover, Portus offers a web UI on top of your registry that will give you a clear overview of the images and tags that are stored in your registry.

Portus offers tons of important features like:

... and so much more. Take a look at this page and have fun with all the possibilities!

When we started this project, we already had some images on the Docker Hub, and we enjoyed using it. That being said, soon enough we realized the problems that Docker Hub entails:

  • You have to trust another entity to store and manage your Docker images.
  • A centralized hub for all your images is not always a viable option. What if Docker Hub goes down?
  • As a user, you should be able to escape vendor lock-in.

Fortunately for us, Docker has a project called Distribution that addressed one of our biggest concerns: being able to deploy an on-premise Docker registry that takes care of storing and distributing your private Docker images.

Docker Distribution was designed with the UNIX principle in mind of "do one thing and do it well". For this reason, Distribution only takes care of storing and distributing your images, and offers an API so services can be built on top of it. There are two main aspects of said API:

  • An authorization procedure that works with Docker.
  • The ability to fetch the catalog of images and modify it.

With this in mind, we started Portus to address all of our concerns in regards to distributing images inside of an organization, while providing a clear user interface. Moreover, we released Portus as free software. We did that because:

  • We didn't want to put the pressure of vendor lock-in to our users.
  • We wanted to contribute back to the community around container technologies.

Deploying in production

Since Portus is free software, you can deploy it in a wide variety of ways. That being said, we mainly recommend two deployment procedures:

  • The RPM package: we maintain a project in OBS in which we provide RPMs for openSUSE. This is perfect if you plan to deploy Portus in a "traditional way". Moreover, the RPM includes some utilities like portusctl which will help you on the installation and the upgrade of Portus.
  • The official Docker image maintained by us. This is the way to deploy Portus if you are interested on using Docker, or one of the orchestration solutions that the community has to offer.

Development

All the information related to development is written in our Github Wiki. In there, you can find some articles about this. In particular:

One of the most common problems when deploying Portus is failing at configuring SSL. We are sure that, at this point, if you are having problems with SSL it is not because of a bug in either Portus or the Docker registry, but rather:

  • You are missing something on how Portus has to be setup in order for it to use SSL. Check out this page on the documentation for more info.
  • Your setup is malfunctioning. You are using your own setup and there is a piece of it that is not working fine, or the communication between the processes you are using is broken. For this, check out the setups that we describe in the documentation, or check out our Google group or the reported issues for some hints. It's possible that someone else is using a setup that is similar to yours and therefore reading the discussion might help you.

We are not going to lie: the deployment of Portus can be a daunting task considering the amount of moving pieces and the complexity of some of these pieces. For this reason, it's easy to have errors on your deployment due to some missing step or some misunderstanding. Because of this, we have had quite some questions on this regard, or invalid bug reports. If you are facing any problem in Portus, consider these steps:

  • First of all, check that your question is not already answered in the official documentation. If you were following a page in the documentation, make sure that you followed it step by step.
  • Make sure that your question is not already answered in our Google Group. If this is not the case, feel free to ask your question there, we will try to be as diligent as possible.
  • Another possibility is to check whether your issue is already known to us. You can take a look here. If you find a suitable issue, feel free to add a comment with your specific case as specified here.
  • Lastly, if you have gone through all the previous steps and you are sure that this is an issue on Portus itself, then submit a new issue as specified here.