Analytics Worker

Optional analytics ingestion worker for self-hosted Fossa. Powers the Cockpit dashboards (DORA, lifecycle, classifier).

The analytics worker is an optional worker role (WORKER_ROLE=analytics) that powers the Cockpit dashboards (DORA-style metrics, PR lifecycle, and LLM-based PR classifier).

Cockpit analytics is 100% free and open-source. Running the analytics worker as a dedicated service keeps analytical aggregation queries separated from real-time code-review pipelines.

What it does

A separate Node process running the same image as worker (fossa-ai-worker), selected at boot via WORKER_ROLE=analytics. Two crons fire from this process and only this process:

• Ingestion (ANALYTICS_INGESTION_CRON, default */30 * * * *) — reads pull requests and review sessions from Mongo + the OLTP Postgres, projects them into the analytics schema.
• Classifier (ANALYTICS_CLASSIFIER_CRON, default */15 * * * *) — calls an LLM to tag each PR with a type (feature/bugfix/refactor/etc).

Isolating it from the main worker keeps the code-review event loop unaffected by long-running ingestion queries.

Topology

The analytics warehouse is a Postgres schema, not a separate database. Two supported layouts:

• Shared Postgres (recommended for self-hosted) — leave ANALYTICS_PG_DB_HOST empty. The config loader falls back to the main API_PG_DB_* vars and creates an analytics schema in the same instance. One DB to back up and operate.
• Dedicated Postgres — set the full ANALYTICS_PG_DB_* block to point at a separate instance. Use this when you want analytical queries fully isolated from the OLTP write path.

Enabling in Self-Hosted

1. Add the service to docker-compose.yml

worker-analytics:
    image: ghcr.io/brittytino/fossa-worker:latest
    platform: linux/amd64
    container_name: fossa-worker-analytics
    environment:
        - ENV=production
        - NODE_ENV=production
        - WORKER_ROLE=analytics
    networks:
        - shared-network
        - fossa-backend-services
    restart: unless-stopped
    env_file:
        - .env
    depends_on:
        - db_fossa_postgres
        - db_fossa_mongodb
        - rabbitmq

The image is identical to the worker service — only WORKER_ROLE=analytics flips it into ingestion mode.

2. Add the analytics block to .env

Shared Postgres (recommended):

# Empty ANALYTICS_PG_DB_HOST → loader reuses API_PG_DB_* and creates the
# `analytics` schema in the main instance.
ANALYTICS_PG_DB_HOST=
ANALYTICS_PG_DB_SCHEMA=analytics

# Cron schedules (UTC).
ANALYTICS_INGESTION_CRON=*/30 * * * *
ANALYTICS_CLASSIFIER_CRON=*/15 * * * *

Dedicated Postgres:

ANALYTICS_PG_DB_HOST=your-analytics-host
ANALYTICS_PG_DB_PORT=5432
ANALYTICS_PG_DB_USERNAME=analytics
ANALYTICS_PG_DB_PASSWORD=...
ANALYTICS_PG_DB_DATABASE=fossa_analytics
ANALYTICS_PG_DB_SCHEMA=analytics

ANALYTICS_INGESTION_CRON=*/30 * * * *
ANALYTICS_CLASSIFIER_CRON=*/15 * * * *

3. Boot — migrations run automatically

The worker-analytics container shares the same prod-entrypoint.sh as api/worker/webhooks. With RUN_MIGRATIONS=true (installer default), the analytics warehouse migrations (pnpm run analytics:migration:run:prod) run on first boot, creating the analytics schema and its tables.

Reference

Variable	Description	Default
WORKER_ROLE	Must be set to analytics on this container.	required
ANALYTICS_PG_DB_HOST	Analytics Postgres host. Empty → reuse main Postgres.	empty
ANALYTICS_PG_DB_PORT	Analytics Postgres port.	5432
ANALYTICS_PG_DB_USERNAME	Analytics Postgres user. Empty → reuse API_PG_DB_USERNAME.	empty
ANALYTICS_PG_DB_PASSWORD	Analytics Postgres password. Empty → reuse API_PG_DB_PASSWORD.	empty
ANALYTICS_PG_DB_DATABASE	Analytics Postgres database. Empty → reuse API_PG_DB_DATABASE.	empty
ANALYTICS_PG_DB_SCHEMA	Schema name for the warehouse tables.	analytics
ANALYTICS_PG_POOL_MAX	Upper bound on the analytics Postgres pool.	5
ANALYTICS_INGESTION_CRON	Cron schedule for the ingestion run (UTC).	*/30 * * * *
ANALYTICS_CLASSIFIER_CRON	Cron schedule for the LLM PR-type classifier (UTC).	*/15 * * * *

Pausing ingestion (advanced)

To stop ingestion at runtime without removing the container, set ANALYTICS_INGESTION_DISABLED=true and/or ANALYTICS_CLASSIFIER_DISABLED=true and restart worker-analytics. The cron stays scheduled but each tick short-circuits. Use this for incident triage, not as a long-term config — they are managed primarily for cloud and may not appear in the installer template.

Verifying it’s working

After boot, tail the analytics worker logs:

docker compose logs -f worker-analytics

You should see lines like analytics ingestion done in NNNms — {...} every 30 minutes and analytics classifier done ... every 15 minutes. If you don’t, check that WORKER_ROLE=analytics is set on this container only (not on the main worker — that one must stay code-review).