Installation

Prerequisites

Eventum requires Python 3.13 or later.

python --version

Install with uv

uv is a fast Python package manager. If you don't have it yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install Eventum as a tool — this makes the eventum and eventum-keyring commands globally available:

uv tool install eventum-generator

Verify the installation:

eventum --version

Install with pip

pip install eventum-generator

python -m venv .venv && source .venv/bin/activate
pip install eventum-generator

Verify the installation:

eventum --version

Set up a project

After installing Eventum, you need to create a project directory with configuration files. The structure depends on how you plan to run Eventum.

Single generator mode

For quick experiments and one-off generation with eventum generate, all you need is a generator config file and its resources (e.g. templates):

mkdir -p my-project/templates

Create a generator.yml that defines the three-stage pipeline — input, event, and output. See the generator.yml reference for the full schema.

Then run it directly:

eventum generate --id my-gen --path my-project/generator.yml

See First run for a complete step-by-step example with template content.

Application mode

For production use with eventum run — multiple generators, a REST API, and the Studio web UI — you need three config files and a directory for your generators:

mkdir -p eventum/{generators,logs}

Create a minimal eventum.yml — update the paths to match your project location:

server:
  host: "0.0.0.0"
  port: 9474
  auth:
    user: eventum
    password: eventum

generation:
  timezone: UTC
  batch:
    size: 10000

log:
  level: info

path:
  startup: /absolute/path/to/eventum/startup.yml
  generators_dir: /absolute/path/to/eventum/generators
  logs: /absolute/path/to/eventum/logs
  keyring_cryptfile: /absolute/path/to/eventum/cryptfile.cfg

Create a startup.yml — this is where you register your generators. Start with an empty list and add generators as you create them:

[]

Then start the application:

eventum run -c eventum/eventum.yml

Once running, open http://localhost:9474 in your browser to access the Studio UI.

See First run — Run as application for a complete walkthrough with generator examples, and Project structure for a detailed breakdown of how the files relate.

Docker

Official images are available on Docker Hub. Docker does not require a local Python installation.

Project layout for Docker

Prepare your project directory with the similar structure as the application mode above. The Docker container expects the config at /app/config/eventum.yml and generators in the directory you mount:

Since the files will be mounted into the container, use the container paths in eventum.yml:

server:
  host: "0.0.0.0"
  port: 9474
  auth:
    user: eventum
    password: eventum

generation:
  timezone: UTC
  batch:
    size: 10000

log:
  level: info

path:
  startup: /app/config/startup.yml
  generators_dir: /app/generators
  logs: /app/logs
  keyring_cryptfile: /app/config/cryptfile.cfg

Run with Docker

Mount your project directories and expose port 9474 for the API and Studio UI:

docker run --rm \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/generators:/app/generators \
  -v $(pwd)/logs:/app/logs \
  -p 9474:9474 \
  rnv812/eventum-generator:latest

The container starts with eventum run -c /app/config/eventum.yml by default.

Run with Docker Compose

For a more reproducible setup, use a docker-compose.yml:

services:
  eventum:
    image: rnv812/eventum-generator:latest
    ports:
      - "9474:9474"
    volumes:
      - ./config:/app/config
      - ./generators:/app/generators
      - ./logs:/app/logs

docker compose up -d

Once running, open http://localhost:9474 in your browser to access the Studio UI.

Build from source

For development or running the latest unreleased changes:

git clone https://github.com/eventum-project/eventum-generator.git
cd eventum-generator

uv sync

cd eventum/ui
npm ci --legacy-peer-deps
npm run build
cd ../..

uv run eventum --version

What's next