Skip to main content

​
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
monk load MANIFEST
  1. Run Jitsu stack
monk run jitsu/stack
  1. 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: 
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. Inherit Jitsu for event collection and routing. Example: 
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: 
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: 
<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
  • 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:
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:
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