Quick Start

Info

This guide covers running Jitsu locally for exploration and development. For production deployments, please see Production Deployment guide.

Since Jitsu 2.14, a feature-complete Jitsu requires Kubernetes: functions and profile builders run on function servers managed by the Jitsu operator, and connector syncs run as Kubernetes CronJobs. There are two ways to run Jitsu locally:

Development Helm chart (recommended) — deploys the full Kubernetes architecture to Minikube, including the operator and function servers.
Docker Compose (deprecated) — starts the core services without Kubernetes. Functions, profile builders and connector syncs are not available. It will be removed in a future release.

Development Helm chart (recommended)

The Jitsu repository ships development Helm charts (helm/ for the services, helm-deps/ for the dependencies) that deploy the full stack to Minikube with zero configuration: all Jitsu services — console, ingest, bulker, rotor, syncctl, the operator and function servers — plus single-node PostgreSQL, ClickHouse, MongoDB and Kafka (Redpanda) in-cluster. Services are built inside init containers from the repository sources, so no local build step is required, and no host services are needed.

Requirements

Git
Minikube and Helm v3+
Give the Minikube VM at least 8 GB of memory: minikube config set memory 8192 (applies when the cluster is created)

Steps

# Clone the repository
git clone -b newjitsu --single-branch https://github.com/jitsucom/jitsu
cd jitsu/helm
 
# 1. Start minikube
minikube start
 
# 2. Deploy: dependencies first (waits until they are healthy), then the services.
#    Secrets are generated automatically; the console DB schema is applied on every
#    deploy; a checkmark is printed as each component becomes ready.
./dev-deploy.sh deploy
 
# 3. Start tunnel for localhost access (in a separate terminal)
./dev-deploy.sh tunnel

To use an external instance of a dependency, set enabled: false for it in helm-deps/values.yaml and point the matching env.common.KAFKA_BOOTSTRAP_SERVERS / DATABASE_URL / CLICKHOUSE_URL / MONGODB_URL of the main chart at it.

See helm/README.md for configuration, per-service scaling and troubleshooting.

Docker Compose (deprecated)

Warning

The Docker Compose setup is deprecated in favor of the development Helm chart and will be removed in a future release. It does not run the operator or function servers, so functions, profile builders and connector syncs are not available with it.

Requirements

Git
Docker Engine >= 19.03.0

Run

# Clone the repository
git clone -b newjitsu --single-branch --depth 1 https://github.com/jitsucom/jitsu
cd jitsu
 
docker compose -f ./docker/docker-compose.yml up --force-recreate

This starts the core Jitsu services along with their dependencies (PostgreSQL, MongoDB, ClickHouse and Redpanda), plus a few admin UIs (Redpanda Console, PgWeb, Mongo Express).

Once running, open http://localhost:3000 in your browser and login with admin@jitsu.com / admin123. Data ingestion instructions are available right in the UI.

Service	URL
Console (UI)	http://localhost:3000
Ingest (events API)	http://localhost:3049
Bulker	http://localhost:3042
Rotor	http://localhost:3401
Syncctl (optional, requires Kubernetes)	http://localhost:3043

To start only the third-party dependencies (e.g. to run Jitsu services from your IDE):

docker compose -f ./docker/docker-compose.yml --profile jitsu-dependencies up --force-recreate

Configuration

Configuration is overridden via environment variables or a docker/.env.local file (do not edit docker/.env — it holds the defaults). Commonly changed variables:

Name	Default value	Description
`SEED_USER_EMAIL` `SEED_USER_PASSWORD`	Optional Default: `admin@jitsu.com / admin123`	Initial admin user credentials. The very first user is created with those credentials. Please change the password right after first login.
`SEED_DEMO_CONFIGURATION`	Optional Default: `true`	Creates a demo stream and destination on first start.
`RELEASE_TAG`	Optional Default: `latest`	Docker image tag of Jitsu services to run.
`JITSU_INGEST_PUBLIC_URL`	Optional Default: `http://localhost:3049`	URL where Jitsu Ingest is reachable by the clients sending events. When Jitsu is deployed on a remote server, set it to your server URL, e.g.: `http://your-domain:3049`.
`POSTGRES_PASSWORD` `CLICKHOUSE_PASSWORD` `MONGODB_PASSWORD`	Optional	Passwords of the bundled dependency services. See `docker/README.md` for the defaults.
`BULKER_TOKEN` `CONSOLE_TOKEN` `SYNCCTL_TOKEN`	Optional Default: `dev-auth-key`	Secrets used for internal communication between Jitsu components. Generate random values if the installation is reachable from outside your machine.
`GITHUB_CLIENT_ID` `GITHUB_CLIENT_SECRET`	Optional	Use GitHub OAuth instead of (or in addition to) password auth.
`DISABLE_SIGNUP`	Optional	Set to `true` if you don't want to allow new users to sign up.

See the full list of variables in docker/README.md and in the Configuration Reference.

Connector syncs with Docker Compose

Sync jobs require a Kubernetes cluster even in the compose setup — a cluster can be attached via the syncctl service, see Connector Syncs.