Karakoram

module

v0.4.2 Latest Latest Go to latest Published: Oct 30, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/KarakoramDev/Karakoram

Links

Open Source Insights

README ¶

Karakoram

Karakoram is a multi-platform, self-hosted control plane for database and stateful-service orchestration inside your infrastructure, without Kubernetes or a hosted coordinator. A Go control plane provides a REST API, karactl CLI and web UI; providers supply infrastructure, while you operate the installation, credentials, data and recovery procedures. Zerops is the reference provider. Dokploy and Nomad are also available; see Providers for their status.

Engines

Versions below are catalog defaults; each engine section lists supported versions and upgrade paths.

Release status and provider-specific availability are centralized in engine availability.

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
Weaviate	Official Weaviate 1.40.1; mixed-license binary, community features only	Single; 3–9 data members with three fixed Raft voters	Native S3 full; no PITR	Weaviate
PostgreSQL	Percona PostgreSQL 17.11.1 default; majors 16/17/18; extension profiles	Single; Patroni/etcd HA (3/5); Citus distributed; 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
Keycloak	Official Keycloak 26.8.1; OpenJDK 21	One native runtime with a PostgreSQL binding	Through the source PostgreSQL cluster	Keycloak
OpenBao	OpenBao 2.7.1	1/3/5 members; integrated Raft or bound PostgreSQL storage	Raft snapshots to S3; PostgreSQL storage uses source recovery; no PITR for Raft	OpenBao
Temporal	Temporal 1.32.1 (also 1.31.4); ui-server 2.56.0	Combined server; split stateless roles on bound PostgreSQL; Dokploy/Nomad only, not Zerops	Source PostgreSQL backup plus cluster-state manifest; requires binding service	Temporal
MySQL	Percona Server for MySQL 8.4.11-11 default; majors 8.4/8.0	Single; Group Replication single-primary (3/5); ProxySQL	XtraBackup full/incremental and GTID-based PITR	MySQL
Percona XtraDB Cluster	PXC 8.4.11-11.1 default; majors 8.4/8.0; separate `pxc` engine driver	Galera cluster (3/5); one ProxySQL-routed writer	Separate PXC backup provenance; full/incremental and PITR	PXC
Neo4j Community	Neo4j 2026.09.0 / 2026.10.0 (default); Temurin Java 21	Single member only	Offline system + graph dumps; full outage; no PITR	Neo4j

Providers

Karakoram is multi-platform; a namespace selects the infrastructure provider that provisions its members.

Provider	Role / runtime	Infrastructure and guide
Zerops	Reference provider	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 Providers for capability differences and Operating costs 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.
Safe fleet operations, control-plane backup/recovery, notifications and backup drills, verified offline.

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 provider in Providers. 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.26+, 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 · Providers · Operating costs · Upgrade
Control plane: Architecture · Clusters and operations · Backups and storage · Namespaces and relays · Zerops provider · Dokploy provider · Nomad provider · 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
Control-plane recovery: State backups and provider rebuild runbooks
Backup verification: Scheduled and manual restore drills
Notifications: Webhook, Slack and email channels, signatures and delivery guarantees
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
Weaviate: Overview · Access and TLS · Backups · Operations
PostgreSQL: Overview · Extension profiles: PostGIS, pgvector, TimescaleDB · Service bindings · Distributed Citus · Access and TLS · Backups and PITR · Operations
Supabase: Overview · Components and availability · Operations
Keycloak: PostgreSQL binding, routing and administrator recovery
OpenBao: Overview · API access and TLS · Raft backups and recovery · Operations and unseal
Temporal: Overview and prerequisites · Access and TLS · Operations and recovery
MySQL and PXC: Overview · Configuration · Access and TLS · Backups and PITR · Operations and recovery · Native verification
Neo4j Community: Overview · Access and TLS · Offline backups · 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 ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api 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/keycloak Package keycloak supervises the native Keycloak distribution.	Package keycloak supervises the native Keycloak distribution.
agent/mysql SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
agent/neo4j Package neo4j supervises a single native Neo4j Community server JVM.	Package neo4j supervises a single native Neo4j Community server JVM.
agent/openbao The member configuration is cached in plaintext by the shared agent.	The member configuration is cached in plaintext by the shared agent.
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.
agent/temporal Package temporal supervises native Temporal server roles and the Web UI.	Package temporal supervises native Temporal server roles and the Web UI.
agent/weaviate
agentapi SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
agentrollout Package agentrollout schedules opt-in provider-managed agent upgrades.	Package agentrollout schedules opt-in provider-managed agent upgrades.
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 SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
certificates Package certificates provides secret-free expiry inventory and durable daily warnings.	Package certificates provides secret-free expiry inventory and durable daily warnings.
cli Package cli implements karactl, the Karakoram REST API command-line client.	Package cli implements karactl, the Karakoram REST API command-line client.
cpbackup SPDX-License-Identifier: Apache-2.0	SPDX-License-Identifier: Apache-2.0
cronutil Package cronutil defines the scheduling grammar shared by control-plane policies.	Package cronutil defines the scheduling grammar shared by control-plane policies.
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.
domain
drills Package drills verifies backups using isolated, server-managed restore targets.	Package drills verifies backups using isolated, server-managed restore targets.
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/enginetest SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
engine/keycloak Package keycloak reconciles an independent PostgreSQL binding consumer.	Package keycloak reconciles an independent PostgreSQL binding consumer.
engine/keycloak/kcspec Package kcspec defines the private Keycloak member configuration.	Package kcspec defines the private Keycloak member configuration.
engine/mysql SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
engine/mysql/myspec SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
engine/nativeartifacts Package nativeartifacts pins the native programs installed by engine members.	Package nativeartifacts pins the native programs installed by engine members.
engine/neo4j SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
engine/neo4j/neo4jspec Package neo4jspec defines the Neo4j Community member payload carried in agentapi.MemberConfig.EngineSpec and the bounded agent action protocol shared by the control-plane provider (internal/engine/neo4j) and the member runner (internal/agent/neo4j).	Package neo4jspec defines the Neo4j Community member payload carried in agentapi.MemberConfig.EngineSpec and the bounded agent action protocol shared by the control-plane provider (internal/engine/neo4j) and the member runner (internal/agent/neo4j).
engine/openbao Package openbao manages TLS-only OpenBao servers with Raft or opt-in PostgreSQL storage.	Package openbao manages TLS-only OpenBao servers with Raft or opt-in PostgreSQL storage.
engine/openbao/baoapi Package baoapi is a minimal OpenBao HTTP API client shared by the control plane and the member agent.	Package baoapi is a minimal OpenBao HTTP API client shared by the control plane and the member agent.
engine/openbao/baospec Package baospec defines the OpenBao member specification and the bounded control-plane ↔ member-agent protocol.	Package baospec defines the OpenBao member specification and the bounded control-plane ↔ member-agent protocol.
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/pgprofile Package pgprofile is the shared availability and curated SQL authority for PostgreSQL profiles.	Package pgprofile is the shared availability and curated SQL authority for PostgreSQL profiles.
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/pxc Package pxc composes the shared MySQL lifecycle with Galera replication.	Package pxc composes the shared MySQL lifecycle with Galera replication.
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
engine/temporal SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
engine/temporal/tspec Package tspec defines the secret-bearing Temporal member contract shared by the control plane and the member agent.	Package tspec defines the secret-bearing Temporal member contract shared by the control plane and the member agent.
engine/weaviate SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
engine/weaviate/wvapi Package wvapi implements the Weaviate v1 REST administration API.	Package wvapi implements the Weaviate v1 REST administration API.
engine/weaviate/wvspec Package wvspec defines the encrypted Weaviate member wire contract.	Package wvspec defines the encrypted Weaviate member wire contract.
events
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/dokploy
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.
maintenance Package maintenance evaluates permission to start new member disruptions.	Package maintenance evaluates permission to start new member disruptions.
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.
netguard Package netguard implements DNS-rebinding-safe outbound connection policy.	Package netguard implements DNS-rebinding-safe outbound connection policy.
notify SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors
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.
pgbinding Package pgbinding defines how a consumer service binds to an existing Karakoram PostgreSQL cluster: the control plane creates the consumer's databases and one least-privilege owning login role on the source, seals the role password, and blocks source deletion while the binding exists.	Package pgbinding defines how a consumer service binds to an existing Karakoram PostgreSQL cluster: the control plane creates the consumer's databases and one least-privilege owning login role on the source, seals the role password, and blocks source deletion while the binding exists.
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.
reconciler
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.
scheduler
secrets
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 SPDX-License-Identifier: Apache-2.0	SPDX-License-Identifier: Apache-2.0
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
e2e
oidc-issuer command TEST ONLY: this issuer automatically authenticates every visitor as oidctest.	TEST ONLY: this issuer automatically authenticates every visitor as oidctest.