Self-Hosted Install

Get event7 running on your machine in 5 minutes. This guide covers the self-hosted Docker deployment — everything runs locally, no external dependencies.

Prerequisites

Docker and Docker Compose (v2)
Git
Python 3.12+ (only for seed scripts — not needed to run event7)

Quick install

1. Clone the repository

git clone https://github.com/KTCrisis/event7.git
cd event7

2. Generate an encryption key and configure

# Generate a Fernet encryption key
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# Copy the env file and edit it
cp backend/.env.example backend/.env

Open backend/.env and set ENCRYPTION_KEY with the key you just generated. Set DB_PROVIDER=postgresql for self-hosted mode.

3. Start everything

docker compose -f docker-compose.local.yml up -d --build

4. Verify

curl http://localhost:8000/health
# → {"status":"healthy","services":{"redis":"ok","database":"ok"}}

Service	URL	Description
Frontend	`http://localhost:3000`	Next.js UI
Backend	`http://localhost:8000`	FastAPI + Swagger (/docs)
Apicurio	`http://localhost:8081`	Schema Registry (empty)
PostgreSQL	`localhost:5432`	Database (auto-migrated)
Redis	`localhost:6379`	Cache

Connect your registry

Open http://localhost:3000/settings and click Connect Registry.

Local Apicurio (included)

Provider: Apicurio

URL: http://apicurio:8080

Use the Docker service name, not localhost:8081. The backend connects from inside the Docker network.

Confluent Cloud

Provider: Confluent Cloud

URL: https://psrc-xxxxx.region.aws.confluent.cloud

API Key + Secret from Confluent Cloud → Schema Registry → API credentials.

Confluent Platform

Provider: Confluent Self-Managed

URL: http://your-sr-host:8081

Username + Password for LDAP/RBAC auth. No auth if open.

Karapace & Redpanda use the Confluent-compatible API — connect them as "Confluent Cloud" or "Confluent Self-Managed" with their SR URL. No additional configuration needed.

Seed with demo data (optional)

The seed scripts create a realistic e-commerce domain — perfect for evaluation. Skip this if you want to connect your own registry.

Seed schemas into Apicurio

cd backend
pip install requests pyyaml   # if not already installed
python scripts/seed_apicurio.py --url http://localhost:8081

Creates 10 Avro + JSON Schema subjects with cross-references and multiple versions.

Seed event7 governance data

python scripts/seed_event7.py --url http://localhost:8000

Creates 9 enrichments, 7 channels (Kafka + RabbitMQ + Redis), 9 bindings, and 7 governance rules.

Skip specific sections

python scripts/seed_event7.py --skip-enrichments    # channels + rules only
python scripts/seed_event7.py --skip-channels        # enrichments + rules only
python scripts/seed_event7.py --skip-rules           # enrichments + channels only

What you should see after seeding

Dashboard	Schema count, enrichment coverage %, compatibility chart, governance score funnel
Explorer	10 subjects, multiple versions, Avro + JSON Schema formats
Diff Viewer	com.event7.User → diff v1 vs v2 → role field added
References	Order → Customer → Address chain, orphan detection
Catalog	Broker badges (Kafka/RabbitMQ/Redis), data layers, ownership
Channels	7 channels across 3 broker types, with bindings
Rules	7 governance rules — global + per-subject, with severity levels
Validate	Paste a modified schema → PASS/WARN/FAIL verdict

Configuration reference

All configuration is done via environment variables in backend/.env. The Docker Compose file passes them to the backend container.

Backend environment variables

ENCRYPTION_KEY

Fernet key for encrypting registry credentials at rest. Generate with the python command shown in the Quick Install section above.

required

DB_PROVIDER

Database mode. Always 'postgresql' for self-hosted.

Default: postgresql

required

DATABASE_URL

PostgreSQL connection string. Docker Compose sets this automatically. For manual setup: postgresql://user:pass@host:5432/event7

Default: (set by docker-compose)

REDIS_URL

Redis connection URL. Docker Compose sets this automatically.

Default: redis://localhost:6379

AUTH_ENABLED

Enable JWT authentication. Set to 'false' for local evaluation.

Default: false

CORS_ORIGINS

Allowed CORS origins as a JSON array. Add your frontend URL if not localhost.

Default: ["http://localhost:3000"]

OLLAMA_HOST

Ollama API URL for the AI Agent. Example: http://ollama:11434 (local) or https://ollama.com (cloud). Leave empty to disable AI Agent.

OLLAMA_MODEL

LLM model name. Example: llama3.1:8b (local) or kimi-k2.5:cloud (cloud). Required if OLLAMA_HOST is set.

OLLAMA_API_KEY

API key for Ollama Cloud or OpenAI-compatible providers. Leave empty for local Ollama.

APP_ENV

Environment name. 'development' enables debug mode.

Default: development

APP_DEBUG

Enable debug logging (loguru).

Default: true

Frontend environment variables

File: frontend/.env.local — only needed for manual setup. Docker Compose injects these automatically.

NEXT_PUBLIC_API_URL

Backend API URL. Docker Compose overrides this to the internal service name.

Default: http://localhost:8000

Docker Compose handles most of this. For a standard local deployment, you only need to set ENCRYPTION_KEY and DB_PROVIDER=postgresql in backend/.env. Everything else has working defaults.

Troubleshooting

Backend crashes with "ENCRYPTION_KEY not set"

Generate a Fernet key and add it to backend/.env. The key must be a valid Fernet base64 string — don't invent one, use the generate command.

Frontend shows "Failed to fetch" on every page

Check that the backend is running (curl localhost:8000/health). If you're running manually (not Docker), make sure NEXT_PUBLIC_API_URL points to localhost:8000 in frontend/.env.local.

Cannot connect Apicurio — "Connection failed"

Use http://apicurio:8080 (the Docker service name), not localhost:8081. The backend connects from inside the Docker network.

CORS errors in browser console

CORS_ORIGINS in backend/.env must be a JSON array: ["http://localhost:3000"]. Not a plain string, not missing the quotes.

Database migration errors on startup

The bootstrap SQL runs automatically on first start via docker-entrypoint-initdb.d. If you're re-creating the database, use docker compose down -v to remove the volume, then up again.

Schemas show in Apicurio (localhost:8081) but not in event7

Make sure you connected the registry in event7 Settings using the Docker hostname (apicurio:8080), and that the provider type is set to "Apicurio".

AI Agent shows "Not configured"

Set OLLAMA_HOST and OLLAMA_MODEL in backend/.env. For local Ollama: OLLAMA_HOST=http://host.docker.internal:11434 and OLLAMA_MODEL=llama3.1:8b.

Seed scripts fail with "Connection refused"

The seed scripts connect from your host machine, not from inside Docker. Use localhost URLs: --url http://localhost:8081 for Apicurio, --url http://localhost:8000 for event7.

Manual setup (without Docker)

If you prefer to run the services manually, you'll need PostgreSQL 15+, Redis 7+, and optionally an Apicurio instance running separately.

# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env — set DATABASE_URL, REDIS_URL, ENCRYPTION_KEY, DB_PROVIDER=postgresql
uvicorn app.main:app --reload --port 8000

# Frontend (separate terminal)
cd frontend
cp .env.example .env.local
# Edit .env.local — set NEXT_PUBLIC_API_URL=http://localhost:8000
npm install && npm run dev