Skip to content

Data Agent

The Data Agent connects your databases with cloud installations of CxReports that are accessible via the Internet. It establishes a websocket connection to CxReports and waits for instructions from the server to execute database queries.

Installation

You can install the Data Agent using Docker or the Windows Installer.

Installation via Docker

Prepared Configuration Files

Prepared configuration files are available on GitHub.

To install the application using Docker, follow these steps:

  1. Create a docker-compose.yml file with the following content:
services:
   app:
     image: codaxy/cx-reports-data-agent:latest
     restart: always
     network_mode: host
     secrets:
       - source: appsettings_file
         target: /app/appsettings.Production.json
     volumes:
       - ./data:/root/.config/CxReports/DataAgent

 secrets:
   appsettings_file:
     file: ./appsettings.Production.jsonc
  1. In the same folder, create the appsettings.Production.jsonc file with the following content:
{
  "Tunnels": [
    {
      "ServerUrl": "[url-of-the-cx-reports-instance]",
      "AllowServerProvidedConnectionStrings": false,
      "ConnectionStrings": {
        "DB1": "[database-connection-string]"
      }
    }
  ]
}

  1. Fill in the placeholders with actual values.

  2. Start the agent using the command:

docker compose up

  1. Copy the public server key from the console.

  2. Start the application as a daemon using:

docker compose up -d

  1. Register the agent in CxReports.

  2. Head to your CxReports administration and go to the Data Agents page.

  3. Register the agent using the public key provided.

  4. Register new databases using the agent and try them out in your reports.

Installation on Windows

Follow these steps to install the Data Agent as a Windows Service:

  1. Go to CxReports Data Agent GitHub Repository and download the installer package.
  2. Install the application.
  3. Open C:\Program Files\CxReports\DataAgent\appSettings.json and configure tunnels and allowed connection strings using the instructions in the next section. Note that administrator permissions are required to make changes to this file as it is located inside the Program Files folder.
  4. Navigate to C:\Windows\System32\config\systemprofile\AppData\Roaming\CxReports\DataAgent\logs and open the log file (agent permissions required here as well).
  5. Copy the server public key from the log file.
  6. Go to your CxReports administration and navigate to the Data Agents page.
  7. Register the agent using the public key provided.
  8. Register new databases and test them in reports.

Agent Configuration

The appSettings.json file looks like this:

{
  "Tunnels": [
    {
      "ServerUrl": "[url-of-my-cx-reports-instance]",
      "AllowServerProvidedConnectionStrings":  false,
      "ConnectionStrings": {
        "DB1": "[connection-string-here]"
      }
    }
  ],
  ...
}

In this configuration:

  • ServerUrl is the URL of your CxReports instance.
  • AllowServerProvidedConnectionStrings determines if the server can provide connection strings.
  • ConnectionStrings contains the connection strings for your databases.

Make sure to replace the placeholders with your actual values.

Configuration changes are automatically applied without the need to restart the agent.

By following these instructions, you can successfully install and configure the Data Agent to connect your databases with CxReports.