Portus 2.4 released!

It has been half a year more or less since we released Portus 2.3, and now it’s time to present to you a shiny new version. This version can be seen as a continuation of 2.3, since it simply deepens on some of the ideas introduced in 2.3, and it adds some nice improvements on top of it. We would like to highlight the following changes:


Configuration changes

We have introduced quite some configurable options. Some of them are new, and some other are merely additions to existing ones.

First of all, we have expanded the configuration for the mailer. We are now providing more options so administrators have more flexibility in regards to how they manage SSL/TLS. You can read the update documentation of the mailer here.

Moreover, the delete option has now two new options:

  1. You can allow contributors to delete namespaces/repositories/etc. with the delete.contributors option (it’s set to false by default).
  2. The background process can now automatically remove images that are older than a certain date, or that match a given tag. This is disabled by default and it’s under the delete.garbage_collector option.

You can read more about this here.

LDAP has also seen some updates. First of all, this release includes the changes described in the 2.3.3 release when it comes to encryption, but it also adds the new timeout option, in which you can tune the timeout in seconds for LDAP lookups. You can read more about this here.

We have also expanded the user_permission section, so administrators can further tune what regular users can do. In more details:

  • We have added the create_webhook and the manage_webhook options, in order to restrict webhook management (it is not restricted by default).
  • We have added the push_images option, which accepts three possible values under its policy key:
    • allow-teams: the default policy, which works as how Portus used to work up until now: owners and contributors of teams can push.
    • allow-personal: team policy is removed, non-admin users will only be able to push into their personal namespaces.
    • admin-only: only administrators are allowed to push images.

You can read a summary of the user_permission.push_images option here.

Furthermore, you can now also tune the pagination rule being applied to all UI elements which contain a list (e.g. the list of repositories).

Last but not least, we have increased the default value for the JWT token expiration time, since it has been reported that the default value was just too small.

Moved portusctl into another project

The portusctl tool has been rewritten and moved into its own project. This has allowed us to expand its possibilities, since now it will mainly interact with your Portus instance through the API. The interface of this tool has changed quite a lot, but we kept the ability to execute commands inside of your Portus instance (i.e. the existing exec command). This new tool is already included in Docker images based on this 2.4 version of Portus.

Changes on the API

We would like to highlight the new bootstrap endpoint. This endpoint allows an administrator of a Portus instance to create the first admin user of Portus and to fetch an application token that has been created for this same user. This way, you no longer need the UI in order to perform the first steps of your instance.

Besides this, the Portus UI itself is using more and more this API, instead of using a more traditional approach. Last but not least, we have changed existing endpoints with more refined status codes, better response objects, etc. Make sure to visit the API documentation.


We have introduced a new concept: bots. Bots are regular users that are created by administrators, but with some subtleties:

  • A bot doesn’t own a personal namespace.
  • A bot cannot login via web.
  • A bot can only log in with application tokens (a token is generated automatically when creating a bot).

Namespace deletion

After much delay, we have implemented namespace deletion. You don’t have to change anything from your configuration in order to have this enabled (it depends on the same delete.enabled configuration).

Upgrading from 2.3

As always, you should perform a backup of all your data before doing anything at all. Afterwards, review the configuration changes that have occurred, just in case you’d like to tune some of these options. Finally, you can run again your deployment setup, since the official Docker image will take care of everything at boot time.

Important note: the latest tag from the Docker image is already pointing to the 2.4 release. If you’d like to stay on the 2.3 branch for a little while, make sure to change the label to 2.3 (or 2.3.6, the latest patch-level release).

What’s next

We have already documented the release process for 2.5. You can take a look at our planned features for 2.5 here.