jetbrains/upsource

This is an official Docker image of https://www.jetbrains.com/upsource/. The image is suitable for evaluation purposes as well as for production use.

How to Use This Image

Pull the image from the Docker Hub Repository docker pull jetbrains/upsource:{version}

For the {version}, specify the tag containing Upsource release version including build number. For a list of version tags, check the https://hub.docker.com/r/jetbrains/upsource/tags/.

To see a list of commands that are supported by the image entry point, run the help command: docker run -it --rm jetbrains/upsource:{version} help

The image can be used for building a customized Upsource image containing 3rd-party tools required for code analysis features. See the Tools for source code analysis section for more details.

Start Upsource

To start a container with an Upsource server, run the following command:

docker run -it --name upsource-server-instance  \
    -v {path to data directory}:/opt/upsource/data \
    -v {path to conf directory}:/opt/upsource/conf  \
    -v {path to logs directory}:/opt/upsource/logs  \
    -v {path to backups directory}:/opt/upsource/backups  \
    -p {port on host}:8080 \
    jetbrains/upsource:{version}

In this command, specify the following parameters: {path to data directory} is the host machine directory where Upsource stores its Apache Cassandra database. For a new instance, pass an empty directory. If you do not map this path, you risk losing Upsource data when the container is removed. {path to conf directory} is the host machine directory where Upsource stores configuration files that contain environment settings, JVM options, Hub integration settings, and so on. {path to logs directory} is the host machine directory where Upsource writes log files. {path to backups directory} is the host machine directory where Upsource stores backups. For more information about managing backup files, refer to the https://www.jetbrains.com/help/upsource/backing-up-and-restoring-data.html#CreatingSchedulingBackups

You can omit references to the directories (data, conf, logs, backups) for non-production testing or demo use, but be sure to provide them when running in production. Otherwise, the corresponding application data is stored in anonymous container volumes which have several problems:

• They can be occasionally removed together with the container (docker rm {Id} -f) which causes loss of data.
• They are stored by the Docker Engine on a host machine inside subfolders of /var/docker with cryptic names. It is difficult if even possible to locate application data in this case, especially if the container itself was removed.

The Upsource service is run inside a docker container under the non-root account 13001:13001 (group:id). Before the first container start, set the appropriate access permissions for the host directories passed to the Upsource container. For example: mkdir -p -m 750 {path to data directory} {path to logs directory} {path to conf directory} {path to backups directory} chown -R 13001:13001 {path to data directory} {path to logs directory} {path to conf directory} {path to backups directory}

-p {port on host}:8080 This port mapping instructs the host machine to listen on port {port on host} and propagate all traffic to the port 8080 inside the Docker container.

Access the Running Service

By default, the service starts on {0.0.0.0:8080} inside the Docker container. Port 8080 is mapped to a {port on host} in the start command. This way, the service can be accessed from any machine that has network access to the port {port on host} of the host machine. For example, if the FQDN of the host machine is host.mydomain.com, then the service is available at http://{host.mydomain.com}:{port on host}.

Stop Upsource

To stop the Upsource service gracefully, run the command docker exec {containerId} stop.

The standard docker kill --signal=SIGTERM {containerId} command also executes a graceful shutdown.

You can also use the standard command docker stop, but with caution. By default, this command sends the SIGTERM signal to the Upsource process inside the Docker container, then waits for 10 seconds. If Upsource doesn't manage to finish shutdown within that time period, SIGKILL is sent to the kernel and the Upsource process is killed. This may lead to data corruption. To avoid this outcome, specify an appropriate timeout value when using this command. For example, the following command leaves ample time for the Upsource service to shut down: docker stop -t 1800 {containerId}

Configure Upsource

On first start, a browser-based Configuration Wizard starts on the main service port. For a list of configuration options, refer to the https://www.jetbrains.com/help/upsource/things-to-configure-after-the-first-start.html. When the configuration is complete, the "Welcome to Upsource" page opens. You can also configure Upsource from the command line, including the properties that are set in the Configuration Wizard on the first start. Stop the Upsource service and run the configure command:

docker run -it --rm \
    -v {path to data directory}:/opt/upsource/data \
    -v {path to conf directory}:/opt/upsource/conf  \
    -v {path to logs directory}:/opt/upsource/logs  \
    -v {path to backups directory}:/opt/upsource/backups  \
    jetbrains/upsource:{version} \
    configure \
    {arguments}

In this command, specify the following parameters: {arguments} is a list of product properties or JVM options.

For more details on the format of the configure command, run the docker run -it jetbrains/upsource:{version} help command.

When you execute the configure command, be sure to keep all local system paths in volume mappings the same as the mappings specified in the run command for the main server. Otherwise updates are not applied to the Upsource configuration files.

You can skip the Configuration Wizard on the first run to make Upsource start with the default settings. Run the configure command (before starting Upsource) with the argument: -J-Ddisable.configuration.wizard.on.clean.install=true If you skip the Configuration Wizard on the first run, you must explicitly configure the base-url property (argument --base-url={URL_Upsource_is_available_to_end_users_by}).

Tools for source code analysis

Upsource supports code navigation and analysis for several languages (notably Java, Kotlin, JavaScript, PHP, and Python). Some of those languages are fully supported out of the box, while others require additional tooling to be installed on the Upsource server. The exact requirements vary depending on the source code processed by your Upsource installation. Please refer to the https://www.jetbrains.com/help/upsource/creating-a-project-code-intelligence.html which describes the 3rd-party tools that may be required. The following https://github.com/JetBrains/upsource-with-tools-docker can be used as an example of how to create a new Upsource image with the necessary 3rd-party tools.

Upgrade Upsource

Before you upgrade, check the detailed Upsource https://www.jetbrains.com/help/upsource/upgrade-with-a-docker-distribution.html.

Minor upgrades

A minor upgrade is an upgrade in scope of the same product version (bug-fix release). For instance, upgrades from 3.5.xxxx to 3.5.yyyy and from 2017.1.xxxx to 2017.1.yyyy are minor. Upgrades from 3.5.xxxx to 2017.1.yyyy and from 2017.1.xxxx to 2017.2.yyyy are major, and are described in the next section. If you made no changes to the container, you can just stop the running container, pull a newer version of the Upsource image and run the server with the usual command (providing volumes with application data left from the previous version). If you changed the image, you will need to replicate the changes to the new Upsource server image before running a new version.

The Upgrade Wizard is deployed and listens on the Upsource main port and some non-root context after the container of the new version finishes the startup process. The URL of the Upgrade Wizard is printed at the startup container console and is recorded in the logs. To locate the Upgrade Wizard URL, search for a line in the startup console logs that contains "will be available on". The entire log record looks something like "JetBrains Configuration Wizard will be available on http://{host}:{port}/contextPath?wizard_token={value} after start".

As soon as the Upgrade Wizard is complete, the Upsource service starts.

Major upgrades

Major upgrades can only be performed with the help of a backup. To perform a major upgrade:

• Create a backup while your existing Upsource instance is running.
• Stop the Upsource service.
• Delete the contents of the data and conf folders — the folders you mapped as volumes to the /opt/upsource/data and /opt/upsource/conf inside the container.
• Make sure the date-specific backup folder is located in the default backups directory on a host machine (the one mapped as a volume to the /opt/upsource/backups inside the container). If not, copy backup folder to that directory.
• Pull an image of the latest Upsource version from the Docker Hub Repository (for a list of version tags, check the https://hub.docker.com/r/jetbrains/upsource/tags/).
• Run the new Docker image with the same command as at the initial run, mapping directories in the container to the corresponding directories left on the host machine from the previous installation.
• When startup is complete, the Upsource Configuration Wizard is deployed (the wizard URL is printed in the console output and stored in logs).
• In the Configuration Wizard, choose the Upgrade option and select the location of your backup.

After you complete the wizard steps, the upgraded Upsource service will be started.

License

The Docker image is available under the Upsource license. Upsource is free for perpetual use (up to 10 users). https://www.jetbrains.com/upsource/buy/license.html.

Release Notes

You can find a link to the release notes for the current Upsource version on our https://www.jetbrains.com/upsource/download. To access the release notes for earlier versions and builds, check https://www.jetbrains.com/upsource/download/previous.html.

Feedback

Report issues or suggestions in the https://youtrack.jetbrains.com/issues/UP

Under the Hood

This Docker image is built on top of a base image which includes:

• https://hub.docker.com/_/debian
• Amazon Corretto Jdk 8u222

Upsource Distributed Cluster

You can also deploy Upsource in a distributed cluster. For instructions, refer to the https://www.jetbrains.com/help/upsource/upsource-distributed-installation.html. This is a completely different and fully-distributable type of installation where Upsource is decomposed on several scalable services. Since installation and maintenance of an Upsource Distributed Cluster requires more resources, it might be ***ed as an option if the single-image distributive described on this page doesn't suit well for the company code base (1000+ active users, huge code base).

• https://hub.docker.com/r/jetbrains/upsource-analyzer/
• https://hub.docker.com/r/jetbrains/upsource-frontend/
• https://hub.docker.com/r/jetbrains/upsource-opscenter/
• https://hub.docker.com/r/jetbrains/upsource-psi-broker/
• https://hub.docker.com/r/jetbrains/upsource-psi-agent/
• https://hub.docker.com/r/jetbrains/upsource-cluster-init/
• https://hub.docker.com/r/jetbrains/upsource-proxy/
• https://hub.docker.com/r/jetbrains/upsource-file-clustering/