Upgrade with Docker

This page describes scenarios of upgrading an existing Hub service with the Hub docker image.

Prerequisites

Before you upgrade, perform the following prerequisite tasks:

Create a backup of your current database. Hub does not provide forward database compatibility. Your database is migrated to the format that is compatible with the latest version during the upgrade procedure. This means that you cannot revert to a previous version and continue to use the database that was processed during the upgrade.
Copy the backup of your current database to a secure location just in case you encounter problems with the upgrade and need to roll back to the previous version.

Recommended Upgrade Path

Installation Version	Target Version
1.0	2.0
2.x	2017.1
2017.x	2018.x
2018.x	2019.x
2019.x	2020.x
2020.x	2021.x

Upgrade Docker Installations

Create a backup of the Hub database while your existing Hub installation is running.
Stop the running Hub docker container.
Pull an image of the latest Hub version from the Docker Hub Repository:
docker pull jetbrains/hub:<version>
Where <version> is a full version number of an Hub build. See the complete list of available versions.
Execute the following command to run a container with the new Hub version, that you have pulled from the repository. All other attributes of the command (volumes and port mappings) must be the same as those that you used with the previous version of the Hub image:
docker run -it --name <hub-server-instance> \ -v <path to data directory>:/opt/hub/data \ -v <path to conf directory>:/opt/hub/conf \ -v <path to logs directory>:/opt/hub/logs \ -v <path to backups directory>:/opt/hub/backups \ -p <port on host>:8080 \ jetbrains/hub:<new version>
- In the console, an URL to the web-based configuration wizard is displayed.
Open the URL in a browser. The settings from the current database are displayed:
Review the settings, and click the Upgrade button.

The Hub service starts with the updated Hub version.

Upgrade an Existing Installation from a Database Backup using a Docker Image

You also have the ability to upgrade any installation type using a docker image by downloading a backup copy of your Hub database and using the backup as the upgrade source in the configuration wizard during installation of the latest version.

This procedure can be used to upgrade an MSI or ZIP installation. It can also be used to migrate an installation from one Docker container to another during the upgrade process.

Create a backup of the Hub database while your existing Hub installation is running.
Stop the existing Hub service.
Pull an image of the latest Hub version from the Docker Hub Repository:
docker pull jetbrains/hub:<version>
Where <version> is a full version number of an Hub build.
Create and configure Hub-specific directories on the host machine.
Copy the backup file of the Hub database into the backups directory, that you created in the previous step.
Execute the following command to run a container with Hub server and map Hub data volumes and port:
docker run -it --name <hub-server-instance> \ -v <path to data directory>:/opt/hub/data \ -v <path to conf directory>:/opt/hub/conf \ -v <path to logs directory>:/opt/hub/logs \ -v <path to backups directory>:/opt/hub/backups \ -p <port on host>:8080 \ jetbrains/hub:<version>
Attributes used with the command:
- -it — a flag that attaches Hub container input and output including the startup logs to the terminal window. Note that pressing `Ctrl+C` when the terminal is attached to a container output causes the container to shut down. Use `Ctrl+PQ` in order to detach the terminal from container output. For more details, see the official docker documentation.
- --name hub-server-instance — the arbitrary name for the container.
- -v <path to NNN directory>:/opt/hub/NNN — binding the Hub-specific 'NNN' directory on the host machine to the respective /opt/hub/NNN directory inside the container.
- -p <port on host>:8080 — parameter that defines the ports mapping. It instructs the host machine to listen on port <port on host> and propagate all traffic to the port `8080` inside the docker container.
As the result, Hub service is started on {0.0.0.0:8080} inside the docker container, and port 8080 is mapped to <port on host> that you have specified. This way the service may be accessed from any machine that has network access to <port on host> of the host machine. For instance, if FQDN of the host machine is host.mydomain.com and the <port on host> is 7777, then the service is available at http://host.mydomain.com:7777
The Hub service starts with the web-based Configuration Wizard at the address mentioned above (in our example, it is http://host.mydomain.com:7777). Open the URL in a browser to access the wizard.
In the Configuration Wizard, click Upgrade.
On the Select Upgrade Source page, click the Select button and select the backup file as an upgrade source.
Click Next.
On the Confirm Settings page, review the system settings.
When done, click Upgrade.
- Hub launches its components.
  Do not close the page in the browser until the setup is complete. When the Hub server is ready, you are redirected to the login page.
Enter the credentials for the Hub administrator account and click the Log in button.
- Hub opens to the Users page.
Your Hub installation is upgraded and ready to use.

Last modified: 19 August 2022