> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Jitsu

> Ready-to-run Jitsu container template for open-source customer data platform and event collection.

## Overview

This template provides a production‑ready Jitsu instance as a Monk runnable. You can:

* Run it directly to get a managed customer data platform
* Inherit it in your own infrastructure to collect, transform, and route event data

Jitsu is an open-source data ingestion and event collection engine. It's a self-hosted alternative to Segment, capturing events from websites and apps, transforming them, and sending to data warehouses and analytics tools.

## What this template manages

* Jitsu server for event collection
* Jitsu configurator UI (optional)
* PostgreSQL for configuration storage
* Redis for event queuing
* Web UI and API
* Event transformation engine

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Jitsu stack

```bash theme={null}
monk run jitsu/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in the template files, then `monk load MANIFEST` and run.

Once started:

* Events API: `http://localhost:8001`
* Configurator UI: `http://localhost:7000`

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # Jitsu Server
  jitsu-image-tag: "latest"           # Jitsu image tag
  jitsu-port: "8001"                  # events API port
  jitsu-admin-token: "..."            # admin API token
  
  # Configurator
  configurator-port: "7000"           # UI port
  configurator-user: "admin"          # UI username
  configurator-password: "..."        # UI password
  
  # Database
  postgres-password: "..."            # PostgreSQL password
  redis-password: "..."               # Redis password
```

Data is persisted under `${monk-volume-path}/jitsu` on the host.

## Use by inheritance (recommended for analytics)

Inherit Jitsu for event collection and routing. Example:

```yaml theme={null}
namespace: myapp
events:
  defines: runnable
  inherits: jitsu/stack
  variables:
    jitsu-admin-token: <- secret("jitsu-token")
    configurator-password: <- secret("jitsu-ui-password")
webapp:
  defines: runnable
  containers:
    app:
      image: myorg/webapp
      environment:
        - JITSU_WRITE_KEY=<- secret("jitsu-write-key")
        - JITSU_HOST=http://events:8001
  connections:
    analytics:
      runnable: events
      service: jitsu
```

Set secrets and run:

```bash theme={null}
monk secrets add -g jitsu-token="<admin-token>"
monk secrets add -g jitsu-ui-password="STRONG_PASSWORD"
monk secrets add -g jitsu-write-key="<api-key>"
monk run myapp/webapp
```

## Ports and connectivity

* Service: `jitsu` on TCP port `8001` (Events API)
* Service: `configurator` on TCP port `7000` (UI)
* From web/mobile apps, send events to `http://\<host>:8001/api/v1/event`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Jitsu host.

## Persistence and configuration

* Jitsu config: `${monk-volume-path}/jitsu/data:/home/eventnative/data`
* PostgreSQL data: `${monk-volume-path}/postgres:/var/lib/postgresql/data`
* Redis data: `${monk-volume-path}/redis:/data`

## Features

* **Event Collection**: JavaScript SDK, HTTP API, and server-side libraries
* **Transformations**: Transform events with JavaScript functions
* **Destinations**: Send to 20+ destinations (BigQuery, Redshift, Snowflake, etc.)
* **Schema Mapping**: Map events to destination schemas
* **Real-Time**: Stream events to destinations in real-time
* **Batching**: Batch events for efficiency
* **User Identification**: Merge anonymous and identified users
* **Privacy**: GDPR-compliant, self-hosted data

## Event Collection

JavaScript SDK example:

```javascript theme={null}
<script src="https://cdn.jitsu.com/lib.js"></script>
<script>
  jitsu.init({
    key: "your-write-key",
    tracking_host: "http://localhost:8001"
  });
  
  // Track page view
  jitsu.track('page_view', {
    page: window.location.pathname
  });
  
  // Identify user
  jitsu.identify('user-123', {
    email: 'user@example.com',
    name: 'John Doe'
  });
</script>
```

## Destinations

Jitsu supports:

* **Data Warehouses**: BigQuery, Redshift, Snowflake, ClickHouse
* **Databases**: PostgreSQL, MySQL
* **Analytics**: Google Analytics, Amplitude, Mixpanel
* **Marketing**: Facebook Ads, Google Ads
* **Webhooks**: Custom HTTP endpoints

## Use cases

Jitsu excels at:

* Product analytics data collection
* Customer data platform (CDP)
* Event streaming to data warehouses
* Multi-destination event routing
* Privacy-compliant analytics
* Segment replacement for self-hosted needs

## Related templates

* Combine with monitoring tools (e.g., `prometheus-grafana/`) for observability
* See other templates in this repository for complementary services

## Troubleshooting

* Access configurator UI at `http://localhost:7000`
* Test event ingestion:

```bash theme={null}
curl -X POST http://localhost:8001/api/v1/event \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: your-write-key" \
  -d '{
    "event_type": "test",
    "user_id": "test-user"
  }'
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f local/jitsu/server
```

* For missing events, check Redis queue and destination configs
* Verify destination credentials in configurator UI
* Monitor PostgreSQL for configuration issues
* Check transformation functions for errors
* Ensure host volumes are writable by container users