README
¶
Karakoram
Karakoram is a multi-platform, self-hosted control plane for MongoDB, RabbitMQ, Elasticsearch, PostgreSQL and modular Supabase orchestration inside your infrastructure, without Kubernetes or a hosted coordinator. A Go control plane provides a REST API, karactl CLI and web UI; backends supply infrastructure, while you operate the installation, credentials, data and recovery procedures. Zerops is the reference backend. Dokploy and Nomad are also available; see Backends for their status.
Engines
Versions below are catalog defaults; each engine section lists supported versions and upgrade paths.
| Engine | Distribution/version | Topologies | Backups | Section |
|---|---|---|---|---|
| MongoDB | Percona Server for MongoDB 8.0.32-14; Percona Backup for MongoDB (PBM) 2.16.0-1 | Replica sets; sharded clusters | Logical/physical; point-in-time recovery (PITR) | MongoDB |
| RabbitMQ | RabbitMQ 4.3.6 | 1/3/5/7 brokers | Definitions only; no messages or PITR | RabbitMQ |
| Elasticsearch | Elasticsearch 9.5.5; optional same-version Kibana, Logstash and APM Server | Combined nodes; dedicated masters | Native S3 snapshots | Elasticsearch |
| PostgreSQL | Percona PostgreSQL 17.11.1 default; majors 16/17/18 | Single; Patroni/etcd HA (3/5); ProxySQL client service | pgBackRest full/diff/incr and PITR | PostgreSQL |
| Supabase | PostgreSQL 17 plus release-locked native services | Same database topologies; modular services | PostgreSQL data only; separate S3 object protection required | Supabase |
Backends
Karakoram is multi-platform; a namespace selects the infrastructure backend that provisions its members.
| Backend | Role / runtime | Infrastructure and guide |
|---|---|---|
| Zerops | Reference backend | Managed Ubuntu runtimes, Local Storage and public routing in existing projects; guide. |
| Dokploy | Docker Swarm | Applications and node-local volumes on your Dokploy-managed Docker Swarm; guide. |
| Nomad | Native jobs | Native jobs and dynamic host volumes on your operator-managed Nomad cluster; guide. |
See Backends for capability differences and Pricing for infrastructure costs.
Across engines
- Catalog-driven creation, resource configuration, disk growth and capability-gated cluster operations.
- S3-compatible storage, schedules and recovery.
- Multi-project namespaces and authenticated relays.
- Monitoring, logs and actor-attributed audit activity.
- Local accounts, OIDC, namespace-aware RBAC and owner-scoped API tokens: access control.
Warning: Review critical limits before production use: replica count does not guarantee independent hosts, Local Storage is single-host, and the control plane has one replica.
Quick start
Choose a backend in Backends. For Zerops, use the dashboard-only Quick start, or the installation reference for local deployments, custom names and CLI setup. Dokploy and Nomad installation paths are linked there.
Build from source
Requires Go 1.25+, Node 22.6+, npm and Make:
make build-all # web UI and both Go executables
make test # Go unit/handler tests
# Integration-tagged tests (some require Docker; PostgreSQL/Supabase use native LXC):
go test -tags integration -count=1 -timeout 30m ./...
A Go-only make build without UI assets serves a “UI not built” page. See UI development, Contributing and the end-to-end suite; deployment tests create billable Zerops resources.
Coding agents: read AGENTS.md for repository boundaries and contribution commands.
Documentation index
Keep docs/ beside the repository's api/, ui/ and root README so relative source/reference links resolve.
- Getting started: Overview · Quick start · Install · Backends · Pricing · Upgrade
- Control plane: Architecture · Clusters and operations · Backups and storage · Namespaces and relays · Zerops backend · Dokploy backend · Nomad backend · Monitoring and events · Access control · Security · Operations and troubleshooting · Limitations
- Interfaces: Web UI · CLI · REST API and SDK · MCP quick start · MCP server · Cluster data MCP
- Operator agents: karakoram-operator skill · Skill installation
- MongoDB: Overview · Replica sets · Sharding · Users, roles and TLS · Backups and PITR · Operations
- RabbitMQ: Overview · Access and TLS · Definitions backups · Operations
- Elasticsearch: Overview · Kibana, Logstash and APM · Access and security · Snapshots · Operations
- PostgreSQL: Overview · Access and TLS · Backups and PITR · Operations
- Supabase: Overview · Components and availability · Operations
- Reference: Architecture decisions · Native artifacts · Verification · Contributing · Code of Conduct
Acknowledgements
Thank you to Zerops for providing free-of-charge infrastructure for developing and testing Karakoram.
Karakoram installs Percona Server for MongoDB and Percona Backup for MongoDB from Percona's official repositories. It independently implements orchestration; no OpenEverest code or UI is copied into this repository.
License and trademarks
Karakoram uses the Apache License 2.0; see NOTICE. Dependencies retain their licenses and notices. Percona Server for MongoDB and Percona Backup for MongoDB are Percona products and trademarks. OpenEverest, MongoDB and Zerops names and marks belong to their respective owners; Karakoram is independent and not affiliated with or endorsed by them.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package specification owns the public API source and its reproducible generators.
|
Package specification owns the public API source and its reproducible generators. |
|
cmd
|
|
|
karactl
command
karactl provides the Karakoram REST API command-line interface.
|
karactl provides the Karakoram REST API command-line interface. |
|
karakoram
command
Command karakoram runs the control plane, member agent, readiness probe, and offline recovery.
|
Command karakoram runs the control plane, member agent, readiness probe, and offline recovery. |
|
internal
|
|
|
agent
Package agent supervises member processes and the authenticated node API.
|
Package agent supervises member processes and the authenticated node API. |
|
agent/datamcp
Package datamcp supervises private, authenticated data MCP upstreams.
|
Package datamcp supervises private, authenticated data MCP upstreams. |
|
agent/elastic
Package elastic renders and supervises secured Elastic Stack node processes.
|
Package elastic renders and supervises secured Elastic Stack node processes. |
|
agent/postgres
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
agent/rabbitmq
Package rabbitmq renders and supervises a RabbitMQ member using the shared agent.Engine protocol.
|
Package rabbitmq renders and supervises a RabbitMQ member using the shared agent.Engine protocol. |
|
agent/supabase
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
agent/supabase/gateway
Package gateway renders a self-contained Envoy 1.39 bootstrap.
|
Package gateway renders a self-contained Envoy 1.39 bootstrap. |
|
agent/supabase/initsql
Package initsql owns the curated Supabase prerequisites on PostgreSQL 17.
|
Package initsql owns the curated Supabase prerequisites on PostgreSQL 17. |
|
agent/supabase/logship
Package logship pushes bounded batches of supervised process logs to a private Vector HTTP source.
|
Package logship pushes bounded batches of supervised process logs to a private Vector HTTP source. |
|
agentapi
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
api
Package api provides primitives to interact with the openapi HTTP API.
|
Package api provides primitives to interact with the openapi HTTP API. |
|
apispec
Package apispec parses the embedded public OpenAPI document once for request validation, response-conformance tests and serving it to clients.
|
Package apispec parses the embedded public OpenAPI document once for request validation, response-conformance tests and serving it to clients. |
|
auth
Package auth manages local and OIDC accounts, sealed Ed25519 signing keys, five-minute access cookies, thirty-day rotating refresh families and CSRF.
|
Package auth manages local and OIDC accounts, sealed Ed25519 signing keys, five-minute access cookies, thirty-day rotating refresh families and CSRF. |
|
backupstorage
Package backupstorage provides guarded S3 clients, storage verification and retained-snapshot cleanup.
|
Package backupstorage provides guarded S3 clients, storage verification and retained-snapshot cleanup. |
|
cli
Package cli implements karactl, the Karakoram REST API command-line client.
|
Package cli implements karactl, the Karakoram REST API command-line client. |
|
datamcp
Package datamcp implements the per-cluster data MCP gateway served at /mcp/clusters/{namespace}/{cluster}.
|
Package datamcp implements the per-cluster data MCP gateway served at /mcp/clusters/{namespace}/{cluster}. |
|
datamcp/companion
Package companion manages the stateless data MCP member independently of provider state.
|
Package companion manages the stateless data MCP member independently of provider state. |
|
datamcp/companionspec
Package companionspec is the control-plane to agent payload of the data MCP companion (agentapi.MemberConfig.EngineSpec when Engine is "datamcp").
|
Package companionspec is the control-plane to agent payload of the data MCP companion (agentapi.MemberConfig.EngineSpec when Engine is "datamcp"). |
|
datamcp/nativees
Package nativees implements the versioned, scope-restricted Elasticsearch data tools.
|
Package nativees implements the versioned, scope-restricted Elasticsearch data tools. |
|
datamcp/nativermq
Package nativermq exposes scoped RabbitMQ data tools through the Management API.
|
Package nativermq exposes scoped RabbitMQ data tools through the Management API. |
|
engine
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
engine/elastic
Package elastic reconciles Elasticsearch nodes and their Kibana, Logstash and APM component services.
|
Package elastic reconciles Elasticsearch nodes and their Kibana, Logstash and APM component services. |
|
engine/elastic/agentspec
Package agentspec defines the Elasticsearch engine payload carried in agentapi.MemberConfig.EngineSpec.
|
Package agentspec defines the Elasticsearch engine payload carried in agentapi.MemberConfig.EngineSpec. |
|
engine/elastic/esapi
Package esapi implements Elasticsearch administration over CA-pinned HTTPS.
|
Package esapi implements Elasticsearch administration over CA-pinned HTTPS. |
|
engine/nativeartifacts
Package nativeartifacts pins the native programs installed by engine members.
|
Package nativeartifacts pins the native programs installed by engine members. |
|
engine/postgres
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
engine/postgres/pgspec
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
engine/psmdb
Package psmdb manages Percona Server for MongoDB without Kubernetes.
|
Package psmdb manages Percona Server for MongoDB without Kubernetes. |
|
engine/psmdb/mongoadmin
Package mongoadmin implements authenticated, quorum-aware MongoDB administration.
|
Package mongoadmin implements authenticated, quorum-aware MongoDB administration. |
|
engine/psmdb/pbm
Package pbm orchestrates durable Percona Backup for MongoDB operations through node agents.
|
Package pbm orchestrates durable Percona Backup for MongoDB operations through node agents. |
|
engine/psmdb/users
Package users manages MongoDB application users, custom roles, and the Percona system-user split.
|
Package users manages MongoDB application users, custom roles, and the Percona system-user split. |
|
engine/rabbitmq
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
engine/rabbitmq/mgmt
Package mgmt implements the RabbitMQ Management HTTP API.
|
Package mgmt implements the RabbitMQ Management HTTP API. |
|
engine/rabbitmq/rmqspec
Package rmqspec defines the RabbitMQ member and bounded agent protocol.
|
Package rmqspec defines the RabbitMQ member and bounded agent protocol. |
|
engine/supabase
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
engine/supabase/sbkeys
Package sbkeys generates Supabase credentials without persistence or logging.
|
Package sbkeys generates Supabase credentials without persistence or logging. |
|
engine/supabase/sbspec
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
infra
Package infra defines the backend-neutral infrastructure contract that engine providers, namespaces and the control plane use.
|
Package infra defines the backend-neutral infrastructure contract that engine providers, namespaces and the control plane use. |
|
infra/contracttest
Package contracttest provides the portable infrastructure backend conformance suite.
|
Package contracttest provides the portable infrastructure backend conformance suite. |
|
infra/fake
Package fake implements a deterministic, thread-safe in-memory infrastructure backend for engine tests and backend contract tests.
|
Package fake implements a deterministic, thread-safe in-memory infrastructure backend for engine tests and backend contract tests. |
|
infra/nomad
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
infra/zerops
Package zerops implements Karakoram's Zerops REST infrastructure backend.
|
Package zerops implements Karakoram's Zerops REST infrastructure backend. |
|
mcp
Package mcp embeds the agent interface without adding an authorization path: all operations execute through the cached REST handler with caller credentials.
|
Package mcp embeds the agent interface without adding an authorization path: all operations execute through the cached REST handler with caller credentials. |
|
monitoring
Package monitoring scrapes member exporters and serves retained metric series.
|
Package monitoring scrapes member exporters and serves retained metric series. |
|
namespaces
Package namespaces manages project credentials and enrolled project relays.
|
Package namespaces manages project credentials and enrolled project relays. |
|
oauth
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
orphanvolumes
Package orphanvolumes retries deletion of explicitly recorded, ID-fenced volumes.
|
Package orphanvolumes retries deletion of explicitly recorded, ID-fenced volumes. |
|
pki
Package pki issues cluster and agent certificates from a cluster-scoped CA.
|
Package pki issues cluster and agent certificates from a cluster-scoped CA. |
|
rbac
Package rbac provides persisted, deny-overrides authorization.
|
Package rbac provides persisted, deny-overrides authorization. |
|
redact
Package redact removes credential material from native process diagnostics.
|
Package redact removes credential material from native process diagnostics. |
|
relay
Package relay provides authenticated, namespace-scoped TCP tunnels and relay credentials.
|
Package relay provides authenticated, namespace-scoped TCP tunnels and relay credentials. |
|
s3endpoint
Package s3endpoint defines the storage registration endpoint contract shared by admission, the Go object client and native-engine configuration renderers.
|
Package s3endpoint defines the storage registration endpoint contract shared by admission, the Go object client and native-engine configuration renderers. |
|
server
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
|
SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors |
|
statejson
Package statejson preserves foreign workflow keys while replacing owned state.
|
Package statejson preserves foreign workflow keys while replacing owned state. |
|
store
Package store provides pure-Go SQLite persistence for Karakoram resources.
|
Package store provides pure-Go SQLite persistence for Karakoram resources. |
|
tools/agentgen
command
Command agentgen validates operation safety metadata and generates its lookup.
|
Command agentgen validates operation safety metadata and generates its lookup. |
|
tools/rbacgen
command
Command rbacgen validates operation authorization metadata and generates the operation-ID lookup consumed by the API authorization middleware.
|
Command rbacgen validates operation authorization metadata and generates the operation-ID lookup consumed by the API authorization middleware. |
|
tools/specnoalias
command
Command specnoalias expands YAML aliases for consumers with safe default alias-expansion limits.
|
Command specnoalias expands YAML aliases for consumers with safe default alias-expansion limits. |
|
ui
Package ui serves the Karakoram single-page web application.
|
Package ui serves the Karakoram single-page web application. |
|
version
Package version exposes build metadata shared by the server and CLI.
|
Package version exposes build metadata shared by the server and CLI. |
|
pkg
|
|
|
client
Package client provides the generated Karakoram management API client.
|
Package client provides the generated Karakoram management API client. |
|
test
|
|
|
oidc-issuer
command
TEST ONLY: this issuer automatically authenticates every visitor as oidctest.
|
TEST ONLY: this issuer automatically authenticates every visitor as oidctest. |
Click to show internal directories.
Click to hide internal directories.