Metadata-Version: 2.4
Name: imbi
Version: 2.23.0
Summary: Imbi is a DevOps Service Management Platform designed to provide an efficient way to manage a large environment that contains many services and applications.
Author-email: "Gavin M. Roy" <gavinr@aweber.com>, Dave Shawley <daves@aweber.com>, Alex Campbell <alexc@aweber.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.14
Requires-Dist: imbi-api==2.23.0
Requires-Dist: imbi-assistant==2.23.0
Requires-Dist: imbi-common[databases,llm,mcp,otel,sentry,server]==2.23.0
Requires-Dist: imbi-gateway==2.23.0
Requires-Dist: imbi-mcp==2.23.0
Requires-Dist: imbi-plugin-aws==2.23.0
Requires-Dist: imbi-plugin-github==2.23.0
Requires-Dist: imbi-plugin-google==2.23.0
Requires-Dist: imbi-plugin-logzio==2.23.0
Requires-Dist: imbi-plugin-oidc==2.23.0
Requires-Dist: imbi-plugin-pagerduty==2.23.0
Requires-Dist: imbi-plugin-sonarqube==2.23.0
Requires-Dist: imbi-scheduler==2.23.0
Requires-Dist: imbi-slackbot==2.23.0
Description-Content-Type: text/markdown

# Imbi

Imbi is a DevOps Service Management Platform for managing large environments
containing many services and applications. It provides a centralized service
catalog with metadata management, dependency tracking, ownership hierarchy,
and AI-powered features.

## Features

- **Service Catalog**: Centralized inventory of all services and applications
- **Dependency Tracking**: Graph-based dependency visualization using PostgreSQL + Apache AGE
- **Blueprint System**: Customizable metadata schemas for extending project fields
- **Ownership Hierarchy**: Organization, team, and user-based ownership model
- **AI Assistant**: Conversational AI powered by Claude for service queries
- **MCP Server**: Model Context Protocol server for AI agent access
- **Webhook Gateway**: Inbound event processing from GitHub, PagerDuty, etc.
- **Scheduled Tasks**: Cron, interval, and one-shot triggers that call the API
  or the gateway as a service account, with run history in ClickHouse
- **Analytics**: Operations logs and time-series data via ClickHouse
- **Authentication**: OAuth2/OIDC (Google, GitHub, Keycloak) + local auth

## Architecture

```
                          +--------------------+
                          |       Caddy        |
                          |   reverse proxy    |
                          +--------------------+
                                     |
   +---------+-------------+---------+----+-----------+-------------+
   |         |             |              |           |             |
imbi-ui   imbi-api  imbi-assistant  imbi-gateway   imbi-mcp  imbi-scheduler
(React)  (FastAPI)    (FastAPI)      (FastAPI)    (FastMCP)    (FastAPI)
   |         |             |              |           |             |
   +---------+-------------+---------+----+-----------+-------------+
                                     |
                                imbi-common
                          (shared Python library)
                                     |
                         +-----------------------+
                         |                       |
                 PostgreSQL + AGE           ClickHouse
                 (graph database)           (analytics)
```

`imbi-slackbot` runs alongside these, connecting out to Slack over socket
mode rather than being proxied.

All services run behind [Caddy](https://caddyserver.com/), a powerful and
extensible reverse proxy with automatic HTTPS. The Docker image packages
everything into a single deployable unit that can run all services together
or scale out individual components.

## Quick Start

### Prerequisites

- [Docker](https://docs.docker.com/get-docker/)
- [moon](https://moonrepo.dev) (task runner)

### Running with Docker Compose

The included `compose.yaml` starts Imbi and all backing services:

```bash
# Build and start everything
docker compose up --build -d

# Run initial setup (create admin user, seed permissions)
docker compose exec -it imbi imbi-api setup

# View logs
docker compose logs -f imbi
```

Once running, Imbi is available at **http://localhost:8080** — the only
service published on a fixed host port:

| Service | URL | Description |
|---------|-----|-------------|
| Imbi | http://localhost:8080 | Main application (UI + API via Caddy) |

The backing services are exposed on **ephemeral** host ports (assigned by
Docker) to avoid collisions. Find a service's mapped port with
`docker compose port <service> <container-port>`:

| Service | Container port | Description |
|---------|----------------|-------------|
| PostgreSQL | 5432 | Graph database (Apache AGE); user `postgres`, password `secret` |
| ClickHouse | 8123 | Analytics database HTTP interface |
| Mailpit | 8025 | Email testing UI (captures all outbound email) |
| LocalStack | 4566 | S3-compatible object storage |

### UI Development with Docker Compose

You can use Docker Compose to run the full backend stack while developing
the UI locally with hot-reload:

```bash
# 1. Start the backend services
docker compose up --build -d

# 2. Run initial setup (first time only — creates admin user, seeds permissions)
docker compose exec -it imbi imbi-api setup

# 3. In the ui/ directory, point the dev proxy at the local backend
cd ui
echo 'VITE_API_URL=http://localhost:8080/api' > .env.local
npm install
npm run dev
```

The Vite dev server starts on http://localhost:5173 and proxies `/api`
requests to the Caddy reverse proxy at `:8080`, which routes them to the
appropriate backend service.

Useful services during UI development:

| Service | URL | Use |
|---------|-----|-----|
| UI (dev) | http://localhost:5173 | Vite dev server with hot-reload |
| Imbi (backend) | http://localhost:8080 | Full app via Caddy (API + bundled UI) |

Mailpit (email) and PostgreSQL (graph data) are reachable on the ephemeral
host ports reported by `docker compose port <service> <container-port>`
(see the table above) for inspecting state during development.

### Python Development

The repository is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/):
every library, app, and plugin is a workspace member sharing one
lockfile and one virtualenv. [moon](https://moonrepo.dev) is the task
runner — it owns the lint/format/typecheck/test/build/docs tasks and
downloads its toolchains (node, npm) on first use.

Development prerequisites:

- [moon](https://moonrepo.dev/docs/install) — the version is pinned in
  `.prototools` ([proto](https://moonrepo.dev/proto) users get it
  automatically)
- [uv](https://docs.astral.sh/uv/) — provisions Python 3.14 and the
  shared `.venv`
- [Docker](https://docs.docker.com/get-docker/) — backing services for
  the test suite

```bash
moon run root:setup             # uv sync + pre-commit hooks
moon run root:coverage          # full suite (single session, aggregate coverage)
moon run api:test               # one member's suite in isolation
uv run --env-file .env.test pytest apps/api/tests/endpoints/test_projects.py  # a single suite or file
moon run :lint :typecheck :format   # ruff + basedpyright across every project
uv run pre-commit run --all-files   # reformat (ruff + tombi, write mode)
```

`moon run <member>:test` boots the backing services and writes `.env.test`
first; run `moon run root:services` yourself before invoking `pytest`
directly. `moon query tasks` lists every available task.

### Running the Docker Image

```bash
# Run all services (default)
docker run -p 8080:8080 \
  -e CLICKHOUSE_URL=clickhouse+http://default:password@clickhouse:8123/imbi \
  -e POSTGRES_URL=postgresql://postgres:secret@postgres/imbi \
  -e IMBI_AUTH_JWT_SECRET=your-secret-here \
  -e IMBI_AUTH_ENCRYPTION_KEY=your-encryption-key \
  -e IMBI_API_URL=http://localhost:8080/api \
  -e VITE_API_URL=http://localhost:8080/api \
  ghcr.io/aweber-imbi/imbi:latest

# Run a specific service only
docker run -e IMBI_SERVICE=api ...
docker run -e IMBI_SERVICE=assistant ...
docker run -e IMBI_SERVICE=gateway ...
docker run -e IMBI_SERVICE=mcp ...
docker run -e IMBI_SERVICE=slackbot ...
docker run -e IMBI_SERVICE=scheduler ...   # also needs the vars below

# Run initial setup (create admin user, seed permissions)
docker run -it \
  -e CLICKHOUSE_URL=clickhouse+http://default:password@clickhouse:8123/imbi \
  -e IMBI_AUTH_JWT_SECRET=your-secret-here \
  -e IMBI_AUTH_ENCRYPTION_KEY=your-encryption-key \
  ghcr.io/aweber-imbi/imbi:latest setup
```

### Deploying with Helm

```bash
helm install imbi helm/imbi \
  --set auth.jwtSecret=your-secret \
  --set auth.encryptionKey=your-key
```

See [Helm chart documentation](helm/imbi/README.md) for full configuration.

## Building

### Prerequisites

- [moon](https://moonrepo.dev/docs/install)
- [Docker](https://docs.docker.com/get-docker/)

### Build Commands

```bash
# Build the production Docker image
moon run root:image
```

## Environment Variables

### Required

| Variable | Description | Services |
|----------|-------------|----------|
| `CLICKHOUSE_URL` | ClickHouse connection URL | api, all |
| `IMBI_AUTH_JWT_SECRET` | JWT signing secret | api, assistant, all |
| `IMBI_AUTH_ENCRYPTION_KEY` | Fernet encryption key | api, all |
| `POSTGRES_URL` | PostgreSQL connection URL | gateway, scheduler, slackbot, all |
| `IMBI_SCHEDULER_SA_CLIENT_ID` | Client id of the scheduler's service account | scheduler |
| `IMBI_SCHEDULER_SA_CLIENT_SECRET` | Client secret of the scheduler's service account | scheduler |
| `IMBI_INTERNAL_API_URL` | Bare origin the scheduler connects to imbi-api on (e.g. `http://imbi-api:8000`) | scheduler |

In `all` mode the scheduler is optional: without the service-account
credentials it is simply not started. In `scheduler` mode they are required —
the account is not seeded, so create a service account in the UI, grant it the
`scheduled_task:*` permissions plus whatever its tasks need, and issue it a
client credential. See
[Scheduler configuration](docs/scheduler/configuration.md).

### Optional

| Variable | Description | Default |
|----------|-------------|---------|
| `IMBI_SERVICE` | Service to run (`all`, `api`, `assistant`, `gateway`, `mcp`, `scheduler`, `slackbot`) | `all` |
| `IMBI_API_URL` | Public URL of the API, including the path prefix it is mounted under (e.g. `http://localhost:8080/api`); needed when serving behind the bundled Caddy | - |
| `VITE_API_URL` | Same value as `IMBI_API_URL`; injected into the UI at serve time | - |
| `ANTHROPIC_API_KEY` | Anthropic API key for assistant | - |
| `IMBI_ASSISTANT_ENABLED` | Enable the AI assistant | `false` |
| `IMBI_EMAIL_ENABLED` | Enable email notifications | `false` |
| `IMBI_EMAIL_SMTP_HOST` | SMTP server host | `localhost` |
| `IMBI_EMAIL_SMTP_PORT` | SMTP server port | `587` |
| `IMBI_EMAIL_SMTP_USE_TLS` | Use TLS for SMTP | `true` |
| `IMBI_ENVIRONMENT` | Runtime environment | `development` |
| `IMBI_SCHEDULER_API_PREFIX` | Path the scheduler mounts its routes under (`/status` is never prefixed) | `/api` |
| `IMBI_SCHEDULER_SCHEMA` | Postgres schema holding task definitions | `scheduler` |
| `IMBI_SCHEDULER_GATEWAY_URL` | imbi-gateway base URL for `gateway` targets | `http://localhost:8003` |
| `IMBI_SCHEDULER_MAX_CONCURRENT_RUNS` | Per-process ceiling on runs in flight | `20` |
| `IMBI_SCHEDULER_POLL_INTERVAL` | Upper bound in seconds on the trigger loop's sleep | `30` |

The scheduler has more settings than these; see
[Scheduler configuration](docs/scheduler/configuration.md) for the full set.

## Project Structure

The repository is a monorepo organized as a uv workspace. Every Python
package publishes its own distribution; the root `imbi` package is a
meta-distribution that installs the whole platform.

```
imbi/
├── libraries/
│   └── common/        # imbi-common — shared library (imbi.common)
│       └── {pyproject.toml, src/, tests/}   # every member carries its own tests
├── apps/
│   ├── api/           # imbi-api — core REST API (imbi.api)
│   ├── assistant/     # imbi-assistant — AI assistant (imbi.assistant)
│   ├── gateway/       # imbi-gateway — webhook gateway (imbi.gateway)
│   ├── mcp/           # imbi-mcp — MCP server (imbi.mcp)
│   ├── scheduler/     # imbi-scheduler — scheduled task triggering
│   │                  #   (imbi.scheduler)
│   └── slackbot/      # imbi-slackbot — Slack bot (imbi.slackbot)
├── plugins/           # imbi-plugin-* — first-party plugins (imbi.plugins.*)
│   ├── aws/  github/  google/  logzio/  oidc/  pagerduty/  sonarqube/
├── ui/                # React frontend (npm, not a uv member)
├── docs/              # unified Zensical site
├── pyproject.toml     # workspace root + the `imbi` meta-package
├── container/         # Dockerfile, Caddyfile, and entrypoint.sh for
│                      #   the production image
├── compose.yaml       # Local run of the production image
├── compose.ci.yaml    # Backing services for the test suites
├── helm/imbi/         # Helm chart for Kubernetes deployment
└── .moon/ + moon.yml  # moon task runner configuration (lint/test/build/…)
```

## Documentation

Full documentation is available at
[aweber-imbi.github.io/imbi](https://aweber-imbi.github.io/imbi/) and
covers installation, configuration, administration, and usage.

## License

BSD 3-Clause License. See [LICENSE](LICENSE) for details.
