# 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= #logging.file.name=/cover-reports.log # H2 configuration #reports.h2.path= # External PostgreSQL DB config #spring.profiles.active=postgres #spring.datasource.url=jdbc:postgresql://:/reports #spring.datasource.username=reports #spring.datasource.password= # Upload Authentication #reports.users.upload.username=username #reports.users.upload.password=password # Export API Authentication #reports.users.api.username=username #reports.users.api.password=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.
`Export API Authentication`	If you wish to add authentication to the export API, define the settings in this section. See #export-api-authentication for details.

### **Setting properties with environment variables (global)** {% tabs %} {% tab title="Windows" %} Edit the `cover-reports.xml` file in your Cover Reports installation. Edit/add the following environment variables in the `` 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_USERS_UPLOAD_USERNAME value="username"/>
<env name="REPORTS_USERS_UPLOAD_PASSWORD value="password"/>

<env name="REPORTS_USERS_API_USERNAME value="api-username"/>
<env name="REPORTS_USERS_API_PASSWORD value="api-password"/>

{% endtab %} {% tab title="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_USERS_UPLOAD_USERNAME=username"
Environment="REPORTS_USERS_UPLOAD_PASSWORD=password"

Environment="REPORTS_USERS_API_USERNAME=api-username"
Environment="REPORTS_USERS_API_PASSWORD=api-password"

{% endtab %} {% endtabs %}

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_USERS_UPLOAD...`	If you wish to add authentication to uploads, define the settings using these environment variables. See #upload-authentication for details.
`REPORTS_USERS_API...`	If you wish to add authentication to the export API, define the settings using there environment variables. See #export-api-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: ```shell docker compose down ``` 2. Edit the `docker-compose.yml` file and update the `ports` value. Note that the value specified is in the format `:` - update the `` value only. ```` ```shell ports: - "9090:8080" ``` ```` 3. From the `$COVER_REPORTS_HOME` directory, start Cover Reports using: ```shell 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/joeblogs/.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](/features/cover-cli/cover-cli-admin/telemetry.md) and [Cover Plugin](/features/cover-plugin/cover-plugin-admin/telemetry.md). **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 {% tabs %} {% tab title="Docker" %} 1. Stop Cover Reports by running: `docker compose down` 2. In your `docker-compose.yml` file, add two new environment variables (`REPORTS_USERS_UPLOAD_USERNAME` and `REPORTS_USERS_UPLOAD_PASSWORD`), and replace `` and `` with the username and password to use for uploading reports bundles: ```yaml report-web: depends_on: postgres: condition: service_started environment: REPORTS_USERS_UPLOAD_USERNAME: REPORTS_USERS_UPLOAD_PASSWORD: ``` > **Note:** Use ASCII characters only in your username and password. Also, do **not** use an empty string as this may cause unexpected behaviour. 3. Save your changes to `docker-compose.yml` and start your Cover Reports instance by running: `docker compose up` {% endtab %} {% tab title="Zip / Exe" %} 1. Stop Cover Reports (if currently running). 2. In your `application.properties` file, add two new variables (`reports.users.upload.username=username` and `reports.users.upload.password=password`), replacing `` and `` with the username and password to use for uploading reports bundles: ``` reports.users.upload.username= reports.users.upload.password= ``` > **Note:** Use ASCII characters only in your username and password. Also, do **not** use an empty string as this may cause unexpected behaviour. 3. Save your changes and start your Cover Reports instance. *** Alternatively you can add these two variables to your environment variables: ``` REPORTS_USERS_UPLOAD_USERNAME: REPORTS_USERS_UPLOAD_PASSWORD: ``` {% endtab %} {% endtabs %} {% hint style="info" %} For Cover Reports Release 2025.03.01 or earlier, use `reports.requiredusername`, `reports.requiredpassword`, `REPORTS_REQUIREDUSERNAME`, and `REPORTS_REQUIREDPASSWORD`. For Cover Reports Release 2025.03.02 and later, use `reports.users.upload.username`, `reports.users.upload.password`, `REPORTS_USERS_UPLOAD_USERNAME`, and `REPORTS_USERS_UPLOAD_PASSWORD`. The older property names are deprecated and will be removed in a future release. {% endhint %} #### Disable upload authentication It is possible to explicitly disable upload authentication. This is useful if using a profile which enables it by default, e.g. `oauth2` for [SSO](/features/cover-reports/cover-reports-administrator/sso-with-cover-reports.md). {% tabs %} {% tab title="Docker" %} 1. Stop Cover Reports by running: `docker compose down` 2. In your `docker-compose.yml` file, add the new environment variable (`REPORTS_USERS_UPLOAD_ENABLED` ), and set the value to `false`: ```yaml report-web: depends_on: postgres: condition: service_started environment: REPORTS_USERS_UPLOAD_ENABLED: false ``` 3. Save your changes to `docker-compose.yml` and start your Cover Reports instance by running: `docker compose up` {% endtab %} {% tab title="Zip / Exe" %} 1. Stop Cover Reports (if currently running). 2. In your `application.properties` file, add the new variable (`reports.users.upload.enabled=false` ): ``` reports.users.upload.enabled=false ``` 3. Save your changes and start your Cover Reports instance. *** Alternatively, you can specify this as an environment variable: ``` REPORTS_USERS_UPLOAD_ENABLED: false ``` {% endtab %} {% endtabs %} ### 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](/features/cover-reports/cover-reports-contributor/authentication.md) for details. ## Export API authentication By default, any Diffblue Cover user can access the Cover Reports export API. However, you may want to restrict and/or secure access using API authentication. For example, you may want to restrict access to specific systems only. ### Enable API Authentication The authentication mechanism allows only a single user to be defined. This mechanism is the same as for [upload authentication](https://docs.diffblue.com/features/cover-reports/cover-reports-administrator/configuration-options#upload-authentication), although the API user is separate from the upload user. {% tabs %} {% tab title="Docker" %} 1. Stop Cover Reports by running: `docker compose down` 2. In your `docker-compose.yml` file, add two new environment variables (`REPORTS_USERS_API_USERNAME` and `REPORTS_USERS_API_PASSWORD`), and replace `` and `` with the username and password to use for accessing the API: ```yaml report-web: depends_on: postgres: condition: service_started environment: REPORTS_USERS_API_USERNAME: REPORTS_USERS_API_PASSWORD: ``` > **Note:** Use ASCII characters only in your username and password. Also, do **not** use an empty string as this may cause unexpected behaviour. 3. Save your changes to `docker-compose.yml` and start your Cover Reports instance by running: `docker compose up` {% endtab %} {% tab title="Zip / Exe" %} * Stop Cover Reports (if currently running). * In your `application.properties` file, add two new variables (`reports.users.api.username=username` and `reports.users.api.password=password`), replacing `` and `` with the username and password to use for accessing the API: ```properties reports.users.api.username= reports.users.api.password.password= **Note:** Use ASCII characters only in your username and password. Also, do **not** use an empty string as this may cause unexpected behaviour. * Save your changes and start your Cover Reports instance. *** Alternatively you can add these two variables to your environment variables: {% code fullWidth="true" %} ``` REPORTS_USERS_API_USERNAME: REPORTS_USERS_API_PASSWORD: ``` {% endcode %} {% endtab %} {% endtabs %} #### Disable API authentication It is possible to explicitly disable API authentication. This is useful if using a profile which enables it by default, e.g. `oauth2` for [SSO](/features/cover-reports/cover-reports-administrator/sso-with-cover-reports.md). {% tabs %} {% tab title="Docker" %} 1. Stop Cover Reports by running: `docker compose down` 2. In your `docker-compose.yml` file, add the new environment variable (`REPORTS_USERS_API_ENABLED` ), and set the value to `false`: ```yaml report-web: depends_on: postgres: condition: service_started environment: REPORTS_USERS_API_ENABLED: false ``` 3. Save your changes to `docker-compose.yml` and start your Cover Reports instance by running: `docker compose up` {% endtab %} {% tab title="Zip / Exe" %} 1. Stop Cover Reports (if currently running). 2. In your `application.properties` file, add the new variable (`reports.users.api.enabled=false` ): ``` reports.users.api.enabled=false ``` 3. Save your changes and start your Cover Reports instance. *** Alternatively, you can specify this as an environment variable: ``` REPORTS_USERS_API_ENABLED: false ``` {% endtab %} {% endtabs %} ### Authenticating with the API Once authentication has been enabled, it is up to the client to authenticate with Cover Reports using the configured username and password. This is done by sending a POST request to `/report/authenticate`, where the username and password are provided in the request parameters: * `username` * `password` If the username and password match the required username and password, a [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token) will be returned. This token must then be attached as the [Bearer token in the Authorization HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Authentication#bearer) in all subsequent requests to the API endpoints. --- # 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.diffblue.com/features/cover-reports/cover-reports-administrator/configuration-options.md?ask= ``` 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.