Knowledge Base > Diffblue Cover Reports > 2. Installing / Upgrading Cover Reports

Installing / Upgrading Cover Reports

Installing using docker hub

(If you cannot use docker hub, please see the section below on Installing without docker hub.)

Before installation, ensure you have the following:

Choosing a location

Since Cover Reports is run in docker, the chosen host must have access to docker hub to allow images to be downloaded. Also, the chosen host must be accessible by:

  • Cover CLI
  • Users who want to view reports

Port numbering

Diffblue recommends using the default port of 8080. Should you need to change the port, edit the docker-compose.yml file and change the default from 8080 to the port you want to serve Cover Reports on.

Deploying Cover Reports

To deploy:

  • Log in to your chosen host (e.g. docker hub)
  • Navigate to the directory where the installation is to be made. This will be the home directory of Cover Reports e.g.:

    cd $COVER_REPORTS_HOME
    
  • Copy the Cover Reports docker-compose.yml into $COVER_REPORTS_HOME
  • Start the application in the home directory of Cover Reports using:

    docker-compose up -d
    

The application is now installed and deployed. Once docker has run, you can open your selected host - default http://localhost:8080/ to see a page similar to this:

The -d option allows you to run docker-compose in the background.

Installing without docker hub

If you cannot access dockerhub, e.g. for security reasons, you can use the filename.tar.gz file instead (sent to you with the product update email). 

1. Install the file using the command:

docker load -i /path/filename.tar.gz

2. Continue with the instructions in the section above.

Version number

The version number is at the bottom of the window, on the left.

Pre-loaded sample project

An example project is included with Cover Reports as part of the installation, to help users get started quickly. Click on the Open Demo Project button.

The next step is to use Cover to upload your report bundles into Cover Reports.

Stopping the service

Please use the command:

docker-compose down

Using telemetry in Cover Reports

Using telemetry in Cover Reports gives you vital information on your users. To enable telemetry (allowing clients to send events to Cover Reports), you need to:

  1. Check that you have installed Cover Reports, and make a note of the Cover Reports home page.
  2. Configure the telemetry.properties file:
    • Set backend=cover-reports
    • Set api_url=http://example.com/telemetry/event, where http://example.com must be replaced with the location of the installed Cover Reports service.
  3. Navigate to the Cover Reports home page, e.g. http://localhost:8080/ui
  4. Manually change the URL in the browser to replace the path /ui with /dashboards
  5. From the list shown, select either the Telemetry CLI dashboard for CLI events or the Telemetry Intellij Plugin dashboard for plugin events:

Upgrading Cover Reports

Cover Reports is designed to perform upgrades automatically upon deployment. This means there are no actions required to trigger an upgrade. However, since Cover Reports is already installed, there are a few additional steps needed to replace the current installation.

Please ensure you back up the relevant folder(s) before upgrading

On the Cover Reports host machine:

  • Navigate into the directory on the host machine where Cover Reports is installed 
  • To stop the current system, run: docker-compose down
  • Rename the docker-compose.yml to include the current installation release version in its name, e.g. docker-compose-2022.09.01.yml. (In future, this (and the associated docker TAR file, if used) can be archived.)
  • Copy the new release docker-compose.yml into the same directory
  • If using the docker TAR file, install the docker images into the local repository as before, e.g.: docker load -i cover-reports.tar.gz
  • To start the application, run: docker-compose up -d .

During startup the need to upgrade will be determined. If required, the upgrade process will run. This may take some time, especially where the database has a large number of project runs. It will not be possible to upload new project runs until this upgrade has completed. During this time, viewing reports may also be limited.

The completion of the upgrade will result in the application being up and running and able to upload new project runs. Currently, this can only be determined from the docker logs for the report-web image, which should contain “Upgrade completed successfully”.

Because the upgrade process can take time and the system will be unavailable at this time, it is best to perform the upgrade when there are no users on the system.

System requirements

System requirements for Cover Reports scale with the number of reports uploaded to the server. For a system with approximately 5000 reports uploaded over the course of two weeks, we recommend the following system specifications:

  • 4 vCPUs (e.g. Azure Standard D4s v3)
  • 16 GB memory
  • 30 GB disk size