# Install and update Cover Reports

## Prerequisites

Specific Cover Reports prerequisites are listed below - see [Specs & Reqs](/get-started/specs-and-reqs.md) 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 [Configuration options](/features/cover-reports/cover-reports-administrator/configuration-options.md#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

{% tabs %}
{% tab title="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](https://www.diffblue.com/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
```

3. 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](https://www.diffblue.com/support) if you don't have the download link.
4. From the `$COVER_REPORTS_HOME` directory, start Cover Reports:

```
docker compose up -d
```

5. 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](/features/cover-reports/cover-reports-administrator/configuration-options.md).

<div align="left"><figure><img src="/files/pkc2lamBDmfA1IOwVJKw" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Docker Hub" %}

1. To access the repository please [sign up to Docker Hub](https://hub.docker.com/) and provide [Diffblue Support](https://www.diffblue.com/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](https://docs.docker.com/docker-hub/access-tokens), for example:

```
docker login -u <username> <password_or_token>
```

3. 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](https://www.diffblue.com/support) if you don't have the download link.
4. From the `$COVER_REPORTS_HOME` directory, start Cover Reports:

```
docker compose up -d
```

5. Finally, open your browser and navigate to the Cover Reports Home Page (`<HOSTURL>:8080`). To change the default port see [Configuration options](/features/cover-reports/cover-reports-administrator/configuration-options.md).

<div align="left"><figure><img src="/files/pkc2lamBDmfA1IOwVJKw" alt=""><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

## 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.

{% tabs %}
{% tab title="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 installation:

1. Adjust the configuration file (`cover-reports.xml`) to account for the path of the installation on the host and the path to JAVA
2. 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.
{% endtab %}

{% tab title="Linux Service" %}
For a Linux host that uses `systemd`, you can start and stop the **Cover Reports** service using `systemctl`.
{% endtab %}

{% tab title="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
  {% endtab %}
  {% endtabs %}

5. Once installation is complete, review and set up your configuration options - see [Configuration options](/features/cover-reports/cover-reports-administrator/configuration-options.md) 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.

{% tabs %}
{% tab title="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 installation:

1. Adjust the configuration file (`cover-reports.xml`) to account for the path of the installation on the host and the path to JAVA
2. 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.
{% endtab %}

{% tab title="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.
{% endtab %}
{% endtabs %}

* Once installation is complete, review and set up your configuration options - see [Configuration options](/features/cover-reports/cover-reports-administrator/configuration-options.md) 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](/features/cover-reports/cover-reports-administrator/database-backup.md).

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

{% tabs %}
{% tab title="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:\
   \&#xNAN;**-** For Cover Reports Docker Compose, download the `docker-compose.yml` file to the `$COVER_REPORTS_HOME` directory.\
   \&#xNAN;**-** 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`
   {% endtab %}

{% tab title="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.
   {% endtab %}

{% tab title="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.
   {% endtab %}
   {% endtabs %}

#### 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](https://www.diffblue.com/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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cover-docs-preview.diffblue.com/features/cover-reports/cover-reports-administrator/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.