Configuration options

Cover Reports provides for a range of configuration options.

Non-Docker options

There are several config options available when Cover Reports is run as a Windows Service, Linux Service, Windows .bat, or macOS/Linux .sh. These can be configured locally via the application.properties config file in the folder where the cover-reports instance is running, or globally via environment variables.

Setting properties in the config file (local)

1. If needed, copy the "template" application.properties file from [install]/bin/ to the folder where the cover-reports instance is running. Edit the application.properties file and edit/add the following, as required - if you don't need to change the default values you can leave the line(s) commented out.

# Cover Reports configuration
#server.port=<COVER-REPORTS-PORT>
#logging.file.name=<LOG-PATH>/cover-reports.log

# H2 configuration
#reports.h2.path=<H2-PATH>

# External PostgreSQL DB config
#spring.profiles.active=postgres
#spring.datasource.url=jdbc:postgresql://<DB-SERVER-HOSTNAME>:<DB-SERVER-PORT>/reports
#spring.datasource.username=reports
#spring.datasource.password=<REPORTS-DB-PASSWORD>

# Upload Authentication
#reports.requiredusername=username
#reports.requiredpassword=password

Field	Description
server.port	Cover Reports listens on port 8080 by default. If this port is already in use, you can change it here. Note that if you change the port, this needs to be replicated when accessing the Cover Reports UI (via a browser) and when uploading reports bundles from Cover CLI and Cover Pipeline.
logging.file.name	Cover Reports logs are saved to cover-reports.log by default, in the root directory of your Reports install. You can change the default path if needed.
reports.h2.path	Cover Reports uses a local H2 database for coverage details and general data. Data files are stored in the root directory of your Reports install - you can change the default path if needed.
External PostgreSQL DB config	If you wish to use an external PostgreSQL data in place of the default H2 database, define the settings in this section. See Using an external database server for details.
Upload Authentication	If you wish to add authentication to uploads, define the settings in this section. See Upload authentication for details.

Setting properties with environment variables (global)

Windows

Edit the cover-reports.xml file in your Cover Reports installation. Edit/add the following environment variables in the <service> section, as needed.

<env name="SERVER_PORT" value="8080"/>
<env name="LOGGING_FILE_NAME" value="%BASE%\cover-reports.log"/>
<env name="REPORTS_H2_PATH" value="%BASE%"/>
  
<env name="JAVA_HOME" value="<JAVA-PATH>"/>

<env name="SPRING_PROFILES_ACTIVE" value="postgres"/>
<env name="SPRING_DATASOURCE_URL value="jdbc:postgresql://<DB-SERVER-HOSTNAME>:<DB-SERVER-PORT>/reports"/>
<env name="SPRING_DATASOURCE_USERNAME value="reports"/>
<env name="SPRING_DATASOURCE_PASSWORD value="<REPORTS-DB-PASSWORD>"/>

<env name="REPORTS_REQUIREDUSERNAME value="username"/>
<env name="REPORTS_REQUIREDPASSWORD value="password"/>

macOS/Linux

Edit the cover-reports.service file in your Cover Reports installation. Edit/add the following environment variables in the [Service] section, as needed.

[Service]
User=cover-reports
Environment="SERVER_PORT=8080"
Environment="LOGGING_FILE_NAME=<LOG-PATH>/cover-reports.log"
Environment="REPORTS_H2_PATH=<H2-PATH>"
Environment="JAVA_HOME=<JAVA-PATH>"

ExecStart=<COVER-REPORTS-PATH>/cover-reports/bin/cover-reports

Environment="SPRING_PROFILES_ACTIVE="postgres"
Environment="SPRING_DATASOURCE_URL="jdbc:postgresql://<DB-SERVER-HOSTNAME>:<DB-SERVER-PORT>/reports"
Environment="SPRING_DATASOURCE_USERNAME="reports"
Environment="SPRING_DATASOURCE_PASSWORD="<REPORTS-DB-PASSWORD>"

Environment="REPORTS_REQUIREDUSERNAME="username"
Environment="REPORTS_REQUIREDPASSWORD="password"/>

Field	Description
SERVER_PORT	Cover Reports listens on port 8080 by default. If this port is already in use, you can change it here. Note that if you change the port, this needs to be replicated when accessing the Cover Reports UI (via a browser) and when uploading reports bundles from Cover CLI and Cover Pipeline.
LOGGING_FILE_NAME	Cover Reports logs are saved to cover-reports.log by default, in the root directory of your Reports install. You can change the default path if needed.
REPORTS_H2_PATH	Cover Reports uses a local H2 database for coverage details and general data. Data files are stored in the root directory of your Reports install - you can change the default path if needed.
JAVA_HOME	Java JDK PATH.
COVER-REPORTS-PATH	macOS/Linux executable path for Cover Reports.
SPRING...	If you wish to use an external PostgreSQL data in place of the default H2 database, define the settings using these environment variables. See Using an external database server for details.
REPORTS...	If you wish to add authentication to uploads, define the settings using these environment variables. See Upload authentication for details.

Using an external database server

When using Cover Reports in a production grade environment you also need to provide an external PostgreSQL database in place of the default H2 database:

1. Create a new database and user on the PostgreSQL server.

2. Grant all privileges on the new database to the new user.

3. Define the PostgreSQL settings as detailed above (local config or global environment variables).

Field	Description
spring.profiles.active SPRING_PROFILES_ACTIVE	Profile type - set this value to postgres
spring.datasource.url SPRING_DATASOURCE_URL	URL for the PostgreSQL database created for Cover Reports data, including the name of the database.
spring.datasource.username SPRING_DATASOURCE_USERNAME	Username used to access the database.
spring.datasource.password SPRING_DATASOURCE_PASSWORD	Password used to access the database.

Changing the default port (Docker)

Cover Reports listens on port 8080 by default. If this port is already in use, you can change it in the docker-compose.yml file. Note that if you change the port, this needs to be replicated when accessing the Cover Reports UI (via a browser) and when uploading reports bundles from Cover CLI and Cover Pipeline. To change the port:

1. In your shell, navigate to $COVER_REPORTS_HOME and stop Cover Reports using:

docker compose down

2. Edit the docker-compose.yml file and update the ports value. Note that the value specified is in the format <external-port>:<internal-port> - update the <external-port> value only.

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

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

docker compose up -d

Using telemetry in Cover Reports

Cover Reports can collect usage telemetry from Cover CLI and Cover Plugin installations to give you vital information on usage across your organization.

Telemetry configuration

Telemetry can be configured (if required) using environment variables, and/or a properties file, on the host machine (where Diffblue Cover is being used). Note that these configuration settings apply to Cover CLI and Cover Plugin.

• Environment variables (listed below) always take priority and is the recommended method for configuring telemetry.

• If you use a properties file, create a telemetry.properties file in the home directory under the .diffblue folder (for example, /users/jbrown/.diffblue/telemetry.properties) and define one or more of the properties listed below.

• If an individual environment variable or property is not found, the default value will be used.

Environment variable	Property	Description	Default
DIFFBLUE_TELEMETRY_ EXTERNAL_ENABLED	telemetry. external. enabled	Enable (true) or disable (false) telemetry data for Diffblue. *	true
DIFFBLUE_TELEMETRY_ REPORTS_ENABLED	telemetry. reports. enabled	Enable (true) or disable (false) telemetry data for Cover Reports.	false
DIFFBLUE_TELEMETRY_ REPORTS_HOSTNAME	telemetry. reports. hostname	Hostname of your Cover Reports server.	localhost
DIFFBLUE_TELEMETRY_ REPORTS_PORT	telemetry. reports. port	Port number of your Cover Reports instance	8080
DIFFBLUE_TELEMETRY_ REPORTS_SCHEME	telemetry. reports. scheme	Protocol used to communicate with Cover Reports - http or https	http

* Disabling the Diffblue endpoint for telemetry data is only available to Diffblue Cover Enterprise Edition customers.

For general Telemetry config detail, refer to the telemetry topics for Cover CLI and Cover Plugin.

Example telemetry.properties file:

# Copyright 2021-2024 Diffblue Limited. All Rights Reserved.
# Example telemetry.properties file
telemetry.external.enabled=true
telemetry.reports.enabled=true
telemetry.reports.hostname=localhost
telemetry.reports.port=8080
telemetry.reports.scheme=http

Manage configurations

If you need to manage telemetry configuration across your organization, you can set the environment variables defined above (as needed) and apply these settings across your organization (for example, using a group policy).

Cover Reports - telemetry home page

To view telemetry data for your organization in Cover Reports, navigate to your Cover Reports telemetry home page, e.g. http://cover-reports.mycompany.com:8080/ui/telemetry. From this view, you can select either the CLI tab for CLI events, or the Plugin tab for plugin events:

Upload authentication

By default, any Diffblue Cover user can upload reports bundles to Cover Reports. However, you may want to restrict and/or secure access using upload authentication. For example, you may want to restrict upload to your CI processes only, so that the data and upload timings are consistent.

Enable upload authentication

Docker

1. Stop Cover Reports by running: docker compose down

2. In your docker-compose.yml file, add two new environment variables (REPORTS_REQUIREDUSERNAME and REPORTS_REQUIREDPASSWORD), and replace <username> and <password> with the username and password to use for uploading reports bundles:

  report-web:
    depends_on:
      postgres:
        condition: service_started
    environment:
      REPORTS_REQUIREDUSERNAME: <username>
      REPORTS_REQUIREDPASSWORD: <password>

Note: Use ASCII characters only in your username and password. Also, do not use an empty string as this may cause unexpected behavior.

3. Save your changes to docker-compose.yml and start your Cover Reports instance by running: docker compose up

Zip / Exe

1. Stop Cover Reports (if currently running).

2. In your application.properties file, add two new variables (reports.requiredusername=username and reports.requiredpassword=password), replacing <username> and <password> with the username and password to use for uploading reports bundles:

reports.requiredusername=<username>
reports.requiredpassword=<password>

Note: Use ASCII characters only in your username and password. Also, do not use an empty string as this may cause unexpected behavior.

3. Save your changes and start your Cover Reports instance.

---

Alternatively you can add these two variables to your environment variables:

REPORTS_REQUIREDUSERNAME: <username>
REPORTS_REQUIREDPASSWORD: <password>

For Cover Reports Release 2023.11.01 or earlier, use dashboard.requiredusername, dashboard.requiredpassword, DASHBOARD_REQUIREDUSERNAME, and DASHBOARD_REQUIREDPASSWORD. For Cover Reports Release 2023.11.02 and later, use reports.requiredusername, reports.requiredpassword, REPORTS_REQUIREDUSERNAME, and REPORTS_REQUIREDPASSWORD.

Upload with authentication

Once upload authentication has been enabled, reports bundles can be uploaded from Cover CLI and Cover Pipeline using the username and password defined above. See Authenticated uploads for details.