Reports Engine (ClickHouse)

Cloudless Pyrus

Custom reports are designed to analyze exactly the metrics that matter to your company. They let you see not only the current status of tasks, but also the entire history of actions — this gives a much more complete picture than standard exports.

Learn more about the purpose and benefits of custom reports

The reports engine runs on top of ClickHouse — it's bundled with Pyrus as a separate container. To enable the engine, all you need is one command that tells Pyrus how to connect to ClickHouse:

docker compose run --rm pyrus-setup enable-report-engine \
  --clickhouseMode SingleNode \
  --clickhouseUser default \
  --clickhousePassword 'PASSWORD'

You can run the command as many times as you like — it's safe and only overwrites the parameters you explicitly provide.

Once enabled, the engine starts pushing new events to the analytical database. To make sure historical data is also available in reports, run a separate one‑off indexing job:

docker compose run --rm pyrus-setup --notes-to-analytic

To turn off the reports engine (your data and connection settings will stay intact):

docker compose run --rm pyrus-setup disable-report-engine

Changing the ClickHouse Password

The process is the same whether you're using a single server or a cluster.

Change the user's password in ClickHouse — this is a standard operation. Check out the ALTER USER docs for details.

Pass the new password to Pyrus using the same enable-report-engine command. You can leave out the other parameters — they'll be preserved:

docker compose run --rm pyrus-setup enable-report-engine \
  --clickhouseMode YOUR_MODE \
  --clickhouseUser USER \
  --clickhousePassword 'NEW PASSWORD'

Restart the services that rely on the analytical database:

docker compose restart pyrus-web-api pyrus-async-worker

Deploying in Kubernetes (K8s)

After enabling the reports engine, you may need to restart the web-api and schedule-to-today pods.

Built-in ClickHouse

If you're using the built-in ClickHouse, start by installing the clickhouse-operator:

helm repo add pyrus-datacenter-k8s https://simplygoodsoftware.github.io/pyrus-datacenter-k8s
helm repo update

helm upgrade --install clickhouse-operator \
  pyrus-datacenter-k8s/clickhouse-operator \
  --namespace clickhouse-operator \
  --create-namespace \
  --wait

Then, in your chart's values file, add the following settings:

See details

reportEngine:
  enabled: true

clickhouse:
  internal: true

  keeper:
    enabled: true

  clickhouse:
    enabled: true

External ClickHouse

If you're connecting to an external ClickHouse instance, specify the connection parameters in your values file:

reportEngine:
  enabled: true

clickhouse:
  internal: false

  clusterName: <cluster name>

  externalUser: <username>
  externalUserPassword: <user password>
  externalHost: <clickhouse host>
  externalPort: <clickhouse port>

Migrating Historical Data

To migrate existing data into the analytical database, create a pod manifest. Fill in your own values where indicated:

apiVersion: v1
kind: Pod
metadata:
  name: clickhouse-data-migrator
  namespace: pyrus
spec:
  restartPolicy: Never
  containers:
    - name: migrator
      envFrom:
        - configMapRef:
            name: common-variables
      image: simplygoodsoftware/pyrus-setup:<your-data-center-version>
      imagePullPolicy: IfNotPresent
      args:
        - --notes-to-analytic
        - -pc
        - "2"

Once you've filled in the manifest, apply it: