Egeria Workspaces

A fully pre-configured, Docker Compose-based platform for learning, experimenting with, and operating Egeria. It exposes a suite of browser-based tools, Jupyter notebooks, and AI-assistant integrations — no manual wiring required.

This environment is designed for learning and small-team use, not enterprise-wide production. For large-scale deployments see the Planning Guide. Community help: Egeria Slack

Try it now — no installation required

Enter the world of Coco Pharmaceuticals — a fictitious company whose rich metadata landscape brings Egeria's capabilities to life. A live demo is running at egeria.pdr-associates.com.

Register for a free account, step into the shoes of one of their key employees by selecting a persona, and explore a fully pre-loaded Egeria environment in your browser. No Docker, no setup.

When you're ready to run your own copy, see Getting started below.

What you can do here

Capability	How to access	Description
Explore the asset catalog	`/tech-catalog` (The Catalog)	Browse infrastructure, data assets, APIs, processes, surveys and annotations registered in Egeria
Explore metadata	`/egeria-explorer`	Browse the type system, glossary, reference data, digital products, valid values and REST APIs
Audit governance	`/egeria-audit`	Review governance relationships (exceptions, certifications, licenses, users). Rows are filtered by your governance-zone access
Operate the platform	`/egeria-operations`	Monitor servers, integration connectors, governance engines and engine actions with live auto-refresh
Trace lineage	`/lineage`	Trace data flow and dependencies across the metadata landscape
Run notebooks	`http://localhost:8888`	Jupyter Lab pre-configured with `pyegeria`; password `egeria`
Interact via TUI	`/my-egeria`	Terminal-UI portal for browsing your Egeria profile and metadata
Author metadata with AI	MCP servers	Connect Claude Desktop (or any MCP client) to the `dr-egeria` and `pyegeria` MCP servers to read and write metadata conversationally
Catalog files automatically	`exchange-*/landing-area/`	Drop files here; the integration daemon classifies and catalogues them automatically

Getting started

Requirements

Docker Desktop (or podman + podman-compose; see Monitoring Podman with PyCharm)
Egeria platform image 6.0 or later (use tag stable or a specific post-6.0 tag if you have older cached images)

Start the platform

# Coco Pharmaceuticals demo environment (recommended for learning)
./quick-start-local

# Clean-slate environment (your own data)
./fresh-start-local

Both scripts automatically bring up the shared Kafka / PostgreSQL / OpenLineage proxy stack before starting the environment-specific containers.

Then open the web portal (self-signed HTTPS by default — accept the browser warning once, or see Configuring Security for a real certificate):

Quickstart: https://localhost:8843
Freshstart: https://localhost:7843

Reaching it by machine name, or from other machines

On Docker Desktop (Mac, Windows), the scripts publish every port on 127.0.0.1 only, so Egeria, Kafka and Postgres aren't exposed to your network. The stack then answers on localhost only. Your machine's own name (e.g. https://my-mac.local:8843) is refused, because that name resolves to its network address. The end-of-run summary prints localhost URLs and says so.

To reach the stack by machine name or from other machines, add --lan:

./quick-start-local --lan
./fresh-start-local --lan

--lan binds the ports on every interface (0.0.0.0) for that run. Anyone who can reach your machine can then reach Egeria, Kafka and Postgres, so use it on a trusted network. Native Docker Engine and Podman already bind 0.0.0.0 (their containers need it to call each other back), and --demo and the *-multi-host scripts imply it. An EGERIA_BIND_IP exported in your shell always wins: EGERIA_BIND_IP=192.168.1.20 ./quick-start-local binds just that address.

Force a clean rebuild

# Pull latest images and rebuild from scratch
NO_CACHE=1 ./quick-start-local

# Force-refresh only the Egeria platform base image
./quick-start-local --refresh-platform

# pyegeria-web + jupyter install the latest pyegeria from PyPI on every run
# (a cached no-op when it hasn't changed). To hold a specific release instead:
./quick-start-local --pyegeria-version 6.1.20   # pin; persists across re-runs
./quick-start-local --pyegeria-version latest   # clear the pin
./quick-start-local --no-refresh-pyegeria       # skip the check (e.g. offline)

NO_CACHE accepts 1 / true / yes / on; unset or 0 / false / no / off uses the cache.

Optional runtimes started with the quickstart

./quick-start-local --with-airflow-marquez   # also start Airflow + Marquez (Coco DAGs and OpenLineage events)
./quick-start-local --skip-airflow-marquez   # don't start them (they are on by default with --demo)
./quick-start-local --skip-unity-catalog     # skip the Unity Catalog demo containers

Airflow (http://localhost:8072) and Marquez (http://localhost:3000) send their OpenLineage events to Egeria through the shared OpenLineage proxy, so the lineage appears in the portal's /lineage tool. Their ports stay bound to 127.0.0.1 even with --demo or --lan, because Airflow's default login can run code and Marquez has no login. The first run builds the Airflow image, which takes several minutes. See the optional runtimes README for details.

Environments

Three deployment modes are available, all sharing the same Kafka, PostgreSQL and OpenLineage proxy infrastructure.

Egeria Demo — hosted, no setup needed

egeria.pdr-associates.com

Enter the world of Coco Pharmaceuticals — a fictitious company whose rich metadata landscape brings Egeria's capabilities to life. Step into the shoes of one of their key employees by selecting a persona, then explore the platform from that person's perspective.

Register for a free account, pick your persona, and start exploring. Includes scheduled data resets and an admin panel. No Docker required.

Egeria Quickstart — local, pre-loaded with Coco data

The recommended starting point for learning Egeria. Pre-loaded with Coco Pharmaceuticals personas, data assets, governance metadata and scenario content. No authentication wall — opens directly to the portal.

./quick-start-local        # single machine (localhost only on Docker Desktop)
./quick-start-local --lan  # same, also reachable by machine name and from other hosts
./quick-start-multi-host   # accessible from other hosts on your network

Portal: https://localhost:8843 · Platform: https://localhost:9443 · Jupyter: http://localhost:8888

Egeria Freshstart — local, clean slate

An empty Egeria environment for setting up your own metadata, governance policies and integrations. Suitable for a small team. Includes registration-gated access and a private data model.

./fresh-start-local        # single machine
./fresh-start-multi-host   # accessible from other hosts on your network

Portal: https://localhost:7843 · Platform: https://localhost:8443 · Jupyter: http://localhost:7888

Quickstart vs Freshstart — detailed comparison

Both scripts automatically bring up the shared infrastructure stack. Run them side by side without port conflicts.

	egeria-quickstart	egeria-freshstart
Pre-loaded content	Coco Pharmaceuticals personas & data	Clean defaults — set up your own environment
Server prefix	`qs-*`	`fs-*`
Authentication	None (direct portal access)	Registration-gated
Platform secrets	Image-bundled (no host mount required)	Seeded from `compose-configs/egeria-freshstart/secrets/` templates into `runtime-volumes/freshstart-platform-data/secrets` on first run
Exchange tree	`exchange-quickstart/`	`exchange-freshstart/`
Runtime data	`runtime-volumes/quickstart-platform-data/`	`runtime-volumes/freshstart-platform-data/`
Further information	Quickstart README	Freshstart README

Container architecture

flowchart TB
    Browser(["🌐 Browser / Client"])

    subgraph QS["🚀 Egeria Quickstart  (ports 88xx)"]
        QS_Apache["Apache  :8885"]
        QS_API["pyegeria-web FastAPI  :8800"]
        QS_Egeria["Egeria Platform  :9443"]
        QS_Jupyter["Jupyter Lab  :8888"]
    end

    subgraph FS["🌱 Egeria Freshstart  (ports 78xx)"]
        FS_Apache["Apache  :7885"]
        FS_API["pyegeria-web FastAPI  :7800"]
        FS_Egeria["Egeria Platform  :8443"]
        FS_Jupyter["Jupyter Lab  :7888"]
    end

    subgraph SI["⚙️ Shared Infrastructure"]
        Kafka[("Kafka  :9192")]
        PG[("PostgreSQL  :5442")]
    end

    Browser --> QS_Apache & FS_Apache
    Browser --> QS_Jupyter & FS_Jupyter
    QS_Apache -->|reverse proxy| QS_API --> QS_Egeria
    FS_Apache -->|reverse proxy| FS_API --> FS_Egeria
    QS_Egeria & FS_Egeria --> Kafka & PG

Web portal applications

The portal at https://localhost:8843 (quickstart) or https://localhost:7843 (freshstart) groups tiles into three sections, all served by the pyegeria-web container:

Primary tools

Tile	Path	What it does
🐱 The Catalog	`/tech-catalog`	Browse infrastructure assets, data stores, APIs and processes registered in Egeria
🔍 Egeria Explorer	`/egeria-explorer`	Browse metadata — types, glossary, lineage, governance blueprints, information supply chains and more
🔗 Lineage Explorer	`/lineage`	Trace data flow and dependencies across the metadata landscape
🛡️ Egeria Audit	`/egeria-audit`	Review exceptions, certifications and licenses; see who has access to Egeria. Rows filtered by your governance-zone access
🎛️ Egeria Operations	`/egeria-operations`	Monitor and operate the runtime — servers, integration connectors, governance engines and engine actions
📊 Egeria Overview	`/egeria-overview`	Executive summary dashboard — scale, governance coverage, quality, and AI-readiness trends
🗂️ Local Dashboards	`/local-dashboards`	User-authored reporting portal — compose high-level views from Egeria metadata and analytic trends

Workspaces & assistants

Tile	What it does
📓 Jupyter Lab	Interactive notebooks for data science and hands-on Egeria API exploration
🗒️ Obsidian Vault	Open the Coco Pharmaceuticals workbook vault in your local Obsidian (or the browser-based shared install)
🖥️ My Egeria	Explore your Egeria profile, roles, teams, actions and data catalog (TUI via `/my-egeria/`)

Documentation & API references

Tile	Path	What it does
📚 Egeria Workspaces Docs	`/docs/`	User guides, Dr. Egeria templates, Coco scenario walkthroughs, admin docs
⚙️ Admin	`/admin`	Manage the Obsidian session lock, view audit log, add reservations (freshstart only)
📖 Egeria Documentation	`egeria.ai` ↗	Official Egeria project documentation and community resources
📚 Egeria JavaDocs	external ↗	Java API reference for the Egeria platform and connectors
🐍 Python API	`/egeria-explorer#python-api`	pyegeria client reference — classes and methods by domain
🔌 REST APIs	`/egeria-explorer#rest-apis`	Live REST API browser — all open metadata services

Screenshots

The Catalog — Data Assets

The Catalog — Surveys & Annotations

Egeria Explorer — Glossary

Egeria Explorer — Type Explorer

Lineage Explorer

Egeria Audit

Egeria Operations — Servers

Egeria Operations — Integration Connectors

Egeria Operations — Engine Actions

Workspaces

Full tab-by-tab documentation: PyegeriaWebHandler README

AI and MCP integration

MCP servers

Two MCP servers are available for connecting AI assistants (Claude Desktop or any MCP client) directly to Egeria:

Server	Alias	What it does
Dr. Egeria MCP	`dr-egeria`	Author metadata using Dr. Egeria notebook-style commands; dynamic tool discovery, hot-reloading
pyegeria MCP	`pyegeria`	Lower-level metadata queries and operations via the pyegeria API

Configure both in ~/.config/Claude/claude_desktop_config.json — see exchange-quickstart/claude_desktop_config.json.md for a combined example. The quickstart examples use https://localhost:9443 and qs-view-server; switch to https://localhost:8443 and fs-view-server for freshstart.

Example: author and verify a glossary entry

User: "Using dr-egeria, create a glossary called 'Product Catalog', then list all glossaries."

Claude: [dr_egeria_run_block → Create Glossary]
        ✓ Glossary 'Product Catalog' created
        [egeria_list_glossaries]
        • Data Assets · Product Catalog (new) · Business Concepts

Obsidian plugins

Execute Dr. Egeria commands directly from your Obsidian vault:

Call Dr. Egeria: MCP-based (over SSE); dynamic command discovery, content-first architecture (results written via the Obsidian API, no Docker volume permissions required).

Source: obsidian-plugins/call-dr-egeria/
Guide: Call Dr. Egeria Guide · Call Dr. Egeria README

For workspace-specific profiles (work/Work-Obsidian, coco-workbooks): OBSIDIAN_PROFILES.md

Reference: Servers

Four OMAG servers run on the platform:

Server type	Quickstart	Freshstart	Purpose
View Server	`qs-view-server`	`fs-view-server`	Egeria REST API — use this name when configuring `pyegeria`
Integration Daemon	`qs-integration-daemon`	`fs-integration-daemon`	Runs integration connectors that synchronize metadata between systems
Engine Host	`qs-engine-host`	`fs-engine-host`	Runs governance services
Metadata Access Store	`qs-metadata-store`	`fs-metadata-store`	Hosts the metadata repository

Egeria platform architecture

flowchart TB
    subgraph Clients["Client Tools"]
        direction LR
        Web["Web SPAs\nExplorer · Audit · Operations\nCatalog · Lineage"]
        Notebooks["Jupyter / pyegeria"]
        AI["AI Assistants\nClaude / MCP"]
        TUI["My Egeria TUI"]
    end

    VS["View Server\nREST API gateway\nqs-view-server"]

    subgraph BackendServers["Backend Servers"]
        direction LR
        ID["Integration Daemon\nqs-integration-daemon\nMetadata sync connectors"]
        EH["Engine Host\nqs-engine-host\nGovernance services"]
        MAS["Metadata Access Store\nqs-metadata-store\nRepository"]
    end

    PG[("PostgreSQL\nMetadata repository")]
    Kafka{{"Kafka\nEvent bus"}}
    Ext(["External Systems\nfiles · databases · APIs"])

    Clients --> VS
    VS --> ID & EH & MAS
    MAS --> PG
    ID & EH & MAS <--> Kafka
    ID <--> Ext

Reference: Host ports

Ports follow a consistent scheme so both environments can run simultaneously without collisions:

Quickstart → 88xx, Freshstart → 78xx — same last two digits = same function
Container-internal ports are unchanged; only host-published ports follow this scheme
Platform, Kafka and PostgreSQL ports are left at their well-established defaults

Function	Quickstart	Freshstart	Container	Notes
Egeria platform (+ JVM debug)	`9443` / `5005`	`8443` / `5006`	same	fixed — not renumbered
Apache web portal	`8885`	`7885`	`8085`	main entry point
Jupyter (notebook / debug)	`8888` / `8889`	`7888` / `7889`	`7888` / `5678`	password `egeria`
pyegeria-web (FastAPI/MCP)	`8800`	`7800`	`8000`
my-egeria (`my-profile` TUI)	`8820`	`7820` (reserved)	`8020`	via Apache `/my-egeria/`
ProjectExplorer	`8830` (planned)	`7830` (reserved)	tbd	see BACKLOG `PORT-7`
Obsidian (web / https)	`8860` / `8861`	—	`3000` / `3001`	optional
Shared Kafka	`9192`–`9194`	`9192`–`9194`	same	fixed — shared-infra
Shared PostgreSQL	`5442`	`5442`	same	fixed — shared-infra
Shared OpenLineage proxy	`6000` / `6001`	`6000` / `6001`	same	shared-infra

Quickstart Jupyter uses 8888, which is Jupyter's own default — it will collide only if you run another Jupyter server on the host. See BACKLOG.md → Ports & Networking for the full rationale.

Reference: Networking (local vs multi-host)

The -local scripts add a synthetic /etc/hosts entry inside each container mapping your machine's hostname to Docker's host-gateway. This is required on Linux (where host.docker.internal is not automatic) and is the right choice for any single-machine setup.

The -multi-host scripts omit that mapping and expect HOST_FQDN to resolve via real DNS — use these only when Egeria needs to be reachable from other machines on your network.

Demo data synchronization

The user-sync command (and the --sync-* flags in quick-start-local) allows you to synchronize the demo portal's user database and feedback data between different machines. This is particularly useful for maintaining a consistent state across multiple demo environments.

# Pull demo data from a remote host to your local machine
./user-sync --sync-from hedwig:egeria-workspaces/runtime-volumes/demo-sync

# Push local demo data to a remote host
./user-sync --sync-to hedwig:egeria-workspaces/runtime-volumes/demo-sync

# Use specific SSH credentials if needed
./user-sync --sync-to remote-host:path --remote-user myuser --remote-password mypass

Synchronization targets the demo_auth (users) and demo (feedback/audit) schemas in the PostgreSQL coco_pharma database.

For more details on integration with the full startup process, see the help text:

./quick-start-local --help

Repository layout

egeria-workspaces/
├── compose-configs/
│   ├── shared-infra/          # Shared Kafka, PostgreSQL, OpenLineage proxy
│   ├── egeria-quickstart/     # Coco Pharmaceuticals demo environment
│   │   └── PyegeriaWebHandler/  # FastAPI web app + MCP server + static SPA files
│   ├── egeria-freshstart/     # Clean-slate environment
│   │   └── PyegeriaWebHandler/
│   └── optional-associated-runtimes/  # Airflow+Marquez, Apache Atlas, Dagster, Superset,
│                                      # Unity Catalog, DeltaLake/Spark, DuckDB, Milvus, MLflow,
│                                      # Ollama, Prefect
├── exchange-quickstart/       # File exchange: Egeria ↔ Jupyter ↔ host (quickstart)
│   ├── coco-data-lake/        # Coco Pharmaceuticals scenario files
│   ├── distribution-hub/      # Egeria-generated output (logs, survey reports)
│   ├── landing-area/          # Drop files here → auto-catalogued by integration daemon
│   └── loading-bay/           # Bulk ingest: glossaries, open-metadata-archives, secrets
├── exchange-freshstart/       # Same structure, isolated for freshstart
├── runtime-volumes/           # Docker bind-mount data — never commit contents
│   ├── quickstart-platform-data/
│   ├── quickstart-apache-web/
│   ├── freshstart-platform-data/
│   └── freshstart-apache-web/
├── obsidian-plugins/          # Obsidian vault plugins for Dr. Egeria
│   └── call-dr-egeria/        # MCP-based plugin (over SSE)
└── work/                      # Your private working files (git-ignored)

License: CC BY 4.0, Copyright Contributors to the ODPi Egeria project.

Name		Name	Last commit message	Last commit date
.aiassistant/rules		.aiassistant/rules
.claude/skills		.claude/skills
.githooks		.githooks
.github		.github
coco-data/patient-hub		coco-data/patient-hub
coco-workbooks		coco-workbooks
compose-configs		compose-configs
design-docs		design-docs
design-patterns		design-patterns
docs		docs
exchange-freshstart		exchange-freshstart
exchange-quickstart		exchange-quickstart
obsidian-plugins/call-dr-egeria		obsidian-plugins/call-dr-egeria
portal-docs		portal-docs
runtime-volumes		runtime-volumes
templates		templates
tests		tests
work		work
workbooks		workbooks
.env.example		.env.example
.gitignore		.gitignore
.mailmap		.mailmap
AGENTS.md		AGENTS.md
BACKLOG-ARCHIVE.md		BACKLOG-ARCHIVE.md
BACKLOG.md		BACKLOG.md
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CLAUDE.md		CLAUDE.md
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Community-Guide.md		Community-Guide.md
DR_EGERIA_AUTO_LOADING_GUIDE.md		DR_EGERIA_AUTO_LOADING_GUIDE.md
GOVERNANCE.md		GOVERNANCE.md
LICENSE		LICENSE
PYEGERIA_ISSUES.md		PYEGERIA_ISSUES.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
SECURITY.md		SECURITY.md
cert-watch.sh		cert-watch.sh
demo-failback		demo-failback
fresh-start-local		fresh-start-local
fresh-start-multi-host		fresh-start-multi-host
generate-certs.sh		generate-certs.sh
letsencrypt-cert.sh		letsencrypt-cert.sh
letsencrypt-wildcard-cert.sh		letsencrypt-wildcard-cert.sh
poetry.toml		poetry.toml
pyproject.toml		pyproject.toml
quick-start-local		quick-start-local
quick-start-multi-host		quick-start-multi-host
redeploy-demo		redeploy-demo
refresh-local		refresh-local
renew-certs.sh		renew-certs.sh
renew-wildcard-cert.sh		renew-wildcard-cert.sh
user-sync		user-sync

Navigation Menu

Repository navigation

About

Repository files navigation

Egeria Workspaces

Try it now — no installation required

What you can do here

Getting started

Requirements

Start the platform

Reaching it by machine name, or from other machines

Force a clean rebuild

Optional runtimes started with the quickstart

Environments

Egeria Demo — hosted, no setup needed

Egeria Quickstart — local, pre-loaded with Coco data

Egeria Freshstart — local, clean slate

Quickstart vs Freshstart — detailed comparison

Container architecture

Web portal applications

Screenshots

AI and MCP integration

MCP servers

Obsidian plugins

Reference: Servers

Egeria platform architecture

Reference: Host ports

Reference: Networking (local vs multi-host)

Demo data synchronization

Repository layout

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Egeria Workspaces

Try it now — no installation required

What you can do here

Getting started

Requirements

Start the platform

Reaching it by machine name, or from other machines

Force a clean rebuild

Optional runtimes started with the quickstart

Environments

Egeria Demo — hosted, no setup needed

Egeria Quickstart — local, pre-loaded with Coco data

Egeria Freshstart — local, clean slate

Quickstart vs Freshstart — detailed comparison

Container architecture

Web portal applications

Screenshots

AI and MCP integration

MCP servers

Obsidian plugins

Reference: Servers

Egeria platform architecture

Reference: Host ports

Reference: Networking (local vs multi-host)

Demo data synchronization

Repository layout

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages