Self-host¶

DiagramaHub is open source (Apache 2.0) and installs on your own infrastructure with Docker Compose. This section is for whoever operates an instance: installing it, configuring it, exposing it to the internet, connecting external services and keeping it up to date.

Beta software

DiagramaHub is at version 0.x. APIs and data structures may change between versions: read the release notes before upgrading and back up the database.

Requirements¶

Requirement	Detail
Docker + Docker Compose	Everything runs in containers; you don't need Python or Node on the host.
Git	To clone the repository and upgrade.
MongoDB 8	Included as a container in `local-full` mode, or external (Atlas, your own server) in `external-mongodb` mode.
Free ports	`5173` (frontend), `5172` (API) and `27017` (MongoDB, `local-full` only).
Operating system	The `install.sh` installer detects macOS, Ubuntu/Debian, CentOS/RHEL and Fedora.

Services¶

An installation has four services on the diagramahub-network Docker network. Kroki publishes no port: only the backend talks to it.

flowchart LR
    U([Browser]) -->|":5173"| F[frontend<br/>React SPA]
    U -->|":5172 /api/v1"| B[backend<br/>FastAPI]
    subgraph net [diagramahub-network]
        F
        B -->|"http://kroki:8000"| K[kroki<br/>PlantUML · D2 · DBML]
        B -->|MONGO_URI| M[(mongodb<br/>MongoDB 8)]
    end
    B -.->|optional| X[Resend · Stripe · Google OAuth<br/>AI providers · Sentry]

Service	Container	Port	Role
Frontend	`diagramahub-frontend`	5173	Web UI. Mermaid renders in the browser.
Backend	`diagramahub-backend`	5172	REST API, business logic, proxy to Kroki.
Kroki	`diagramahub-kroki`	internal	Server-side rendering for PlantUML, D2 and DBML. Your content never leaves your network.
MongoDB	`diagramahub-mongodb`	27017	Database (`local-full` mode only).

In this section¶

Installation

One-line installer (install.sh) or step-by-step manual install.
Configuration

Full reference of backend and frontend environment variables.
Production

Deployment modes, reverse proxy, HTTPS, CORS and a hardening checklist.
Integrations

Email (Resend), payments (Stripe) and Google sign-in from the admin panel.
Plans and limits

Define your own plans, project/diagram limits and prices.
Maintenance

Upgrading, MongoDB backups, repair scripts, logs and Sentry.
Troubleshooting

Common errors and how to diagnose them.

Quick path¶

Install with install.sh or manually.
Generate and set AI_ENCRYPTION_KEY (see Configuration): without it, AI providers, integrations and authenticator-app MFA cannot be saved.
Open http://localhost:5173: the /setup wizard creates the administrator account (the first registered user is always an admin).
Connect an email engine in Integrations to enable password recovery and email MFA codes.
Before exposing it to the internet, follow the Production guide.