Self-host

Architecture

Services, dependencies, ports, and traffic flow through the Dibbla platform.

The platform is six Go services backed by PostgreSQL, Redis, MinIO (S3-compatible object storage), and Loki (log storage). All inbound traffic enters through the API Gateway, which routes by hostname and path to the appropriate backend.

Component diagram

                                          ┌──→ Auth Service (8090)        ──→ Postgres (auth_db) + Redis
                                          │     [bundled, or → app.dibbla.com hosted]
                                          │
                                          ├──→ Deploy API (8085)          ──→ Postgres (agent_db)
                                          │                                ──→ Kubernetes API
                                          │                                ──→ BuildKit + Container Registry
                                          │                                ──→ Loki (log queries)
                                          │
Internet ──→ Ingress ──→ API Gateway ─────┼──→ Workflow Server (3011)     ──→ Postgres (workflows)
                          (3456)          │                                ──→ Redis + MinIO (artifacts)
                              ▲           │                                ──→ Go Toolserver (gRPC 50051)
                              │           │
                              │           ├──→ Go Toolserver (3010)        ──→ Anthropic + OpenAI
                              │           │                                ──→ Postgres + Redis
                              │           │
                              │           ├──→ Feedback Service (8091)    ──→ Postgres (feedback_db)
                              │           │
                              │           └──→ Deployed app pods (subdomain-routed by Host header)
                              │
                          *.<base-domain> DNS wildcard → Ingress IP

         Cluster-wide DaemonSet:  Grafana Alloy ──→ Loki (writes pod logs)

The Auth Service can either run inside your cluster or be Dibbla’s hosted instance. The other services validate tokens against AUTH_SERVICE_URL, regardless of which one it points at. Workflow Server reuses the Auth Service’s JWT signing key so it accepts the same tokens.

Services

API Gateway

Port: 3456
Image: ghcr.io/dibbla-agents/api-gateway
Role: HTTP reverse proxy. Routes by Host header to backend services or to deployed-app pods. Validates auth tokens via the Auth Service.
Talks to: Auth Service, Deploy API, app pods.
State: stateless.

Auth Service (bundled or hosted)

Ports: 8090 (REST API), 3001 (embedded UI for sign-in)
Image: ghcr.io/dibbla-agents/auth-service
Role: OAuth (Google, Microsoft), JWT issuance and validation, organization/user management, API token management.
Talks to: PostgreSQL, Redis, OAuth providers.
State: schema in auth_db. Migrations run automatically on startup (GORM) — no separate migration job.

You don’t have to run this. Setting AUTH_SERVICE_URL on the Gateway and Deploy API to https://app.dibbla.com points your install at Dibbla’s hosted auth — no in-cluster Postgres for auth, no OAuth client registration of your own. See Configure authentication for both paths.

Deploy API

Ports: 8085 (REST API + WebSocket), 8080 (embedded deployment UI)
Image: ghcr.io/dibbla-agents/deploy-api
Role: Receives dibbla deploy archive uploads, builds images (via BuildKit or Docker daemon), creates Kubernetes Deployments + Services + Ingresses for app workloads, manages app DNS records, queries logs from Loki for the live-logs UI.
Talks to: Kubernetes API (in-cluster RBAC via ClusterRole), optional BuildKit, optional container registry, PostgreSQL (agent_db), Loki.
State: agent_db for secrets, managed-database admin, and deployment metadata.

Workflow Server

Ports: 3011 (HTTP), 50051 (gRPC for tool calls)
Image: ghcr.io/dibbla-agents/workflow-server
Role: Orchestrates user-defined workflows, persists state, manages OAuth tokens for tool calls. Reuses the Auth Service’s JWT signing so it can validate the same tokens.
Talks to: PostgreSQL (workflows), Redis (event broadcast), MinIO (artifact storage), Go Toolserver (gRPC).
State: workflows database, MinIO bucket workflow-artifacts.

Go Toolserver

Port: 3010
Image: ghcr.io/dibbla-agents/go-toolserver
Role: Implements the workflow tool functions. Calls Anthropic and OpenAI APIs for the LLM-backed tools.
Talks to: Anthropic API, OpenAI API, PostgreSQL (agent_db by default), Redis.
State: stateless apart from optional caching.

Feedback Service

Port: 8091
Image: ghcr.io/dibbla-agents/feedback-service
Role: Captures user feedback and crash reports.
Talks to: PostgreSQL (feedback_db).
State: feedback_db.

Data plane

Store	Used by	What’s stored
PostgreSQL	Auth, Deploy API, Workflow, Go Toolserver, Feedback	`auth_db`, `agent_db`, `workflows`, `feedback_db` — separate logical DBs.
Redis	Auth (sessions), Workflow Server (event broadcast)	Active sessions, OAuth state, workflow event streams.
MinIO (S3-compatible)	Workflow Server	Workflow artifacts (`workflow-artifacts` bucket by default).
Loki	Deploy API (queries), Alloy (writes)	App + platform logs. Queried by the Deploy API for the live-logs UI.
Container registry (optional)	Deploy API + BuildKit	Built app images. Disable to use an external registry (ECR, GAR, GHCR, etc.).

When you point at Dibbla’s hosted auth, neither Postgres nor Redis is required (unless you also use the Deploy API’s optional secret/database admin store).

The bundled chart ships local Postgres (pgvector/pgvector:pg17) and Redis (redis:7-alpine) subcharts, plus the minio/minio chart (5.4.0) and the Grafana loki (6.55.0) and alloy (1.8.0) charts. Any of them can be disabled in favor of an external instance — see Install with Helm.

How app routing works

You manage DNS yourself. Point a wildcard record (*.<base-domain>) at your ingress IP and you’re done — the platform doesn’t touch your DNS provider.

Inside the cluster, request flow for a deployed app:

Browser hits https://my-app.<base-domain>. Wildcard DNS resolves to the ingress IP.
Ingress forwards to the API Gateway service.
The Gateway / proxy reads the Host header, looks up the app by alias, and forwards to the matching app pod.

No per-app DNS record is created. Each new dibbla deploy --alias my-app is reachable immediately because the wildcard already covers it.

Network surface

Public ingress is needed for the API Gateway only. Everything else (Auth Service, Deploy API, app pods) is reached via the Gateway.
WebSocket support is required on the ingress: the Deploy API serves live build/log streams over /api/deploy/... WebSockets. Make sure your ingress controller forwards Upgrade and Connection headers.

What you’ll see in `kubectl`

After helm install dibbla …, in the release namespace:

NAME                                READY   STATUS
dibbla-api-gateway-…                1/1     Running
dibbla-auth-service-…               1/1     Running
dibbla-deploy-api-…                 1/1     Running
dibbla-workflow-server-…            1/1     Running
dibbla-go-toolserver-…              1/1     Running
dibbla-feedback-service-…           1/1     Running
dibbla-postgresql-0                 1/1     Running
dibbla-redis-master-0               1/1     Running
dibbla-minio-…                      1/1     Running
dibbla-loki-0                       1/1     Running
dibbla-alloy-…                      1/1     Running   # one per node (DaemonSet)
dibbla-buildkit-…                   1/1     Running   # if enabled
dibbla-container-registry-…         1/1     Running   # if enabled

Plus an Ingress for the API Gateway, and Service objects for each backend. Apps deployed by the Deploy API land in the same namespace by default.