Diffblue Logo
Go to diffblue.com

Get unit tests for your Java code automatically with our free IntelliJ plugin. Download now

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

Installing and Upgrading Cover Reports

Prerequisites

See here for the full prerequisites for Cover Reports.

Please ensure that the server on which Diffblue Cover Reports is deployed can be accessed via the Diffblue Cover CLI on port 8080. This default port can be adjusted by following the instructions below.

Method 1: Installing using Cover Reports .tar.gz bundle

1. Using the link provided by Diffblue, download the Cover Reports .tar.gz bundle e.g. diffblue-cover-reports-2023.02.01.tar.gz

2. From the directory containing the Cover Reports .tar.gz bundle, load the Docker bundle using the command:

docker load -i /path/diffblue-cover-reports-<version>.tar.gz

3. In your shell, navigate to the directory where the installation is to be made; referred to throughout this guide as $COVER_REPORTS_HOME. This will be the home directory of Cover Reports e.g.:

cd $COVER_REPORTS_HOME

4. Using the link provided by Diffblue, download the Cover Reports Docker Compose file docker-compose.yml into $COVER_REPORTS_HOME

5. From the $COVER_REPORTS_HOME directory, start Cover Reports using:

docker compose up -d

Method 2: Installing via Docker Hub

Cover Reports is also available via the authenticated Diffblue Docker Hub repository.

1. To access the repository please sign up to Docker Hub and provide Diffblue Support with your username. Diffblue Support will grant access according to your subscription terms.

2. In your shell, log in to Docker Hub using the docker login command with either your username and password or username and Docker Hub Access Token e.g.:

docker login -u <username>

Then either type your password or paste your access token

3. In your shell, navigate to the directory where the installation is to be made; referred to throughout this guide as $COVER_REPORTS_HOME. This will be the home directory of Cover Reports e.g.:

cd $COVER_REPORTS_HOME

4. Using the link provided by Diffblue, download the Cover Reports Docker Compose file docker-compose.yml into $COVER_REPORTS_HOME

5. From the $COVER_REPORTS_HOME directory, start Cover Reports using:

docker compose up -d

Installation complete

Cover Reports is now deployed and running; once the application has completed loading, you can open Cover Reports using a locally accessible URL e.g. http://localhost:8080/

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 to Cover Reports.

Stopping Cover Reports

1. In your shell, navigate to the directory $COVER_REPORTS_HOME where the existing installation is made

cd $COVER_REPORTS_HOME

2. From the $COVER_REPORTS_HOME directory, stop Cover Reports using:

docker compose down

Using telemetry in Cover Reports

Cover Reports can collect usage telemetry from Diffblue Cover CLI and Diffblue Cover IntelliJ Plugin installations to give you vital information on usage. To enable telemetry:

1. Install Cover Reports

2. In the Diffblue Cover CLI and Diffblue Cover IntelliJ Plugin configuration file telemetry.properties:

  • Set backend=cover-reports
  • Set api_url=http://<Cover Reports Server URL>:<port>/telemetry/event, e.g. api_url=http://cover-reports.company.com:8080/telemetry/event

3. Navigate to the Cover Reports telemetery home page, e.g. http://cover-reports.company.com:8080/dashboards

4. 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 $COVER_REPORTS_HOME directory before upgrading

1. Stop Cover Reports by running: docker compose down

2. In your shell, navigate to the directory $COVER_REPORTS_HOME where the existing installation is made

3. Back up the pre-existing docker-compose.yml by renaming to e.g. docker-compose-2022.09.01.yml

4. Using the link provided by Diffblue, download the latest Cover Reports Docker Compose file docker-compose.yml into the directory $COVER_REPORTS_HOME

5. If using the Cover Reports .tar.gz bundle:

  • Using the link provided by Diffblue, download the latest Cover Reports bundle e.g. diffblue-cover-reports-2023.02.01.tar.gz
  • Load the Docker bundle using the command: docker load -i /path/diffblue-cover-reports-<version>.tar.gz

6. Start the new version of Cover Reports using the command: 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.

Changing the default port

The port used by both Cover CLI and the user’s browser to communicate with Cover Reports can be adjusted in docker-compose.yml. To change the port:

1. In your shell, navigate to the directory $COVER_REPORTS_HOME where the existing installation is made

cd $COVER_REPORTS_HOME

2. From the $COVER_REPORTS_HOME directory, stop Cover Reports using:

docker compose down

3. Using a text editor, change port key. Note the value specified is in the format <external-port>:<internal-port>; the internal port must not be changed e.g. changing the port from default 8080 to 9090 would involve changing:

```shell
	ports:
	  - "8080:8080"
```
to
```shell
	ports:
	  - "9090:8080"
```

5. From the $COVER_REPORTS_HOME directory, start Cover Reports using:

  docker compose up -d

## Suggested next page

Uploading Cover Reports Bundles