Install and update Cover Reports

Prerequisites

Specific Cover Reports prerequisites are listed below - see Specs & Reqs for full details.

Server hosting Cover Reports - Cover Reports Administrator:

• 4GB RAM (8GB recommended), 2GB* minimum available disk space, 4 CPU cores.

• 2GB Java heap allocation, 4GB recommended.

• Docker Install - Docker Engine 20.10.17, Docker Compose v2.10.2, and if you're using Docker Hub you'll also need an internet connection.

• Zip Install & Windows Installer - Java JDK 17+ (and available in your PATH system environment variable). For production use, you'll also need to provide a vanilla PostgreSQL 14 database (see Using an external database server).

• Windows Install - Windows Server 2019 and above, Windows 10 and above.

• All - Network connectivity between the server(s) and client workstations. Note that if the Cover Reports server and database server are on different hosts, good network connectivity between them will ensure good performance.

* Note that the database server will store the data uploaded to Cover Reports. Sufficient storage should be ensured for projected usage.

Client workstation - Cover Reports Contributor:

• Diffblue Cover CLI. The version of the CLI should correspond with the version of Reports to ensure the optimum experience.

• JaCoCo 0.8.3+

• Network connectivity between the user's workstation and the Cover Reports server.

Client workstation - Cover Reports User:

• The latest version of Chrome, Edge, Safari, or Firefox with a screen resolution of 1920 x 1080 or higher.

• Network connectivity between the user's workstation and the Cover Reports server.

Docker Install

Docker Archive

1. Using the link provided by Diffblue, download the Cover Reports .tar.gz file (e.g. diffblue-cover-reports-2023.07.02.tar.gz) to the server you plan to use to host Cover Reports. Contact Diffblue Support if you don't have the download link.

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

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

1. In your shell, navigate to your preferred install directory (we'll now refer to this as $COVER_REPORTS_HOME). Using the link provided by Diffblue, download the Cover Reports Docker Compose file docker-compose.yml to $COVER_REPORTS_HOME. Contact Diffblue Support if you don't have the download link.

2. From the $COVER_REPORTS_HOME directory, start Cover Reports:

docker compose up -d

1. Finally, open a browser on a client PC that has access to the Cover Reports server and navigate to the Cover Reports Home Page (<HOSTURL>:8080). To change the default port see Configuration options.

Docker Hub

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 (from the server you plan to use to host Cover Reports), log in to Docker Hub using the docker login command with either your username and password or username and Docker Hub Access Token, for example:

docker login -u <username> <password_or_token>

1. In your shell, navigate to your preferred install directory (we'll now refer to this as $COVER_REPORTS_HOME). Using the link provided by Diffblue, download the Cover Reports Docker Compose file docker-compose.yml to $COVER_REPORTS_HOME. Contact Diffblue Support if you don't have the download link.

2. From the $COVER_REPORTS_HOME directory, start Cover Reports:

docker compose up -d

1. Finally, open your browser and navigate to the Cover Reports Home Page (<HOSTURL>:8080). To change the default port see Configuration options.

Zip Install (Windows, macOS, Linux)

As an alternative, Cover Reports can be installed using the zip archive. This provides for running Cover Reports as a Windows Service, Linux Service, Windows .bat, or macOS/Linux .sh, and removes the need to use Docker. This also provides various database configuration options to provide further flexibility.

To install Cover Reports from the Zip archive:

1. Using the link provided by Diffblue, download the Cover Reports .zip file - for example, diffblue-cover-reports-2023.10.02.zip

2. In your shell, navigate to your preferred install directory (we'll now refer to this as $COVER_REPORTS_HOME). This will be the home directory of Cover Reports.

3. Extract the contents of diffblue-cover-reports-2023.10.02.zip into the $COVER_REPORTS_HOME directory.

4. Install and start the service or run the script as needed.

Windows Service

To install Cover Reports as a service on a Windows host, open a terminal, navigate to the windows-service folder in your Cover Reports install, and run cover-reports.exe install

Once the service has been installed, you can start and stop the Cover Reports service using the Windows Service Manager.

Linux Service

For a Linux host that uses systemd, you can start and stop the Cover Reports service using systemctl.

Script

From the $COVER_REPORTS_HOME directory, start Cover Reports using the bin/cover-reports script for your operating system:

• bin/cover-reports.bat for Windows

• bin/cover-reports for macOS/Linux

1. Once installation is complete, review and set up your configuration options - see Configuration options for details.

Exe Install (Windows)

Cover Reports can be installed on Windows using the combined Cover CLI & Cover Reports installer.

1. Using the link provided by Diffblue, download the combined Cover CLI & Cover Reports - for example, diffblue-cover-installer-2023.10.02.exe

2. Run the installer and follow the on screen prompts - note that to install Cover Reports, make sure that the Cover Reports option is selected during the install.

3. Install and start the service or run the script as needed.

Windows Service

To install Cover Reports as a service on a Windows host, open a terminal, navigate to the windows-service folder in your Cover Reports install, and run cover-reports.exe install

Once the service has been installed, you can start and stop the Cover Reports service using the Windows Service Manager.

Script

From the $COVER_REPORTS_HOME directory, start Cover Reports using the bin/cover-reports.bat script. Note that during install this script is automatically added to your PATH system variable and can be accessed via a command line.

• Once installation is complete, review and set up your configuration options - see Configuration options for details.

Updating Cover Reports

Cover Reports update/upgrade details are provided below. Note that before you update Cover Reports, Diffblue recommends that you perform a database backup first - see Database backup.

Updating Cover Reports may take some time to complete. During this time you won't be able to upload new reports bundles and the Reports URL won't be accessible.

Cover Reports does not support downgrades. It is not possible to deploy an older version of Reports once it has been upgraded - even in case of failure.

Docker

On your Cover Reports server:

1. Stop Cover Reports by running: docker compose down

2. In your shell, navigate to the $COVER_REPORTS_HOME directory where the existing installation is located and make a copy (backup) of the directory.

3. Rename the docker-compose.yml file in the $COVER_REPORTS_HOME directory - e.g. docker-compose-2023.08.13.yml

4. Using the link provided by Diffblue, download Cover Reports: - For Cover Reports Docker Compose, download the docker-compose.yml file to the $COVER_REPORTS_HOME directory. - For Cover Reports .tar.gz, download the latest Cover Reports bundle (e.g. diffblue-cover-reports-2023.08.01.tar.gz) and load the Docker bundle: docker load -i /path/diffblue-cover-reports-<version>.tar.gz

5. Start the new version of Cover Reports using the command: docker compose up -d

ZIP Install

1. Make a copy of your custom files as needed - application.properties, cover-reports.xml, cover-reports.service

2. Using the link provided by Diffblue, download the latest Cover Reports .zip bundle to your Cover Reports install directory.

3. Stop Cover Reports (if currently running).

4. In your shell, navigate to the Cover Reports install directory and extract the contents of the downloaded zip file.

5. Add your custom files back to the updated installation.

6. Restart Cover Reports.

EXE Install

Windows:

1. Using the link provided by Diffblue, download the combined Cover CLI & Cover Reports - for example, diffblue-cover-installer-2023.10.02.exe

2. Run the installer and follow the on screen prompts - note that to install Cover Reports, make sure that the Cover Reports option is selected during the install.

3. Restart the Cover Reports service.

How to deal with problems during an upgrade

The upgrade process is designed to occur automatically during deployment of a new version. In case an error occurs during an upgrade:

1. Contact Diffblue Support and provide the log files from the report-web application

2. Stop the Reports application

If Reports must be available for use while this problem is investigated:

1. Restore the database backup created immediately prior to the failed upgrade

2. Restart the previously installed version of Reports