README
¶
karakoram.dev · Documentation · Contributing
Self-hosted MongoDB, RabbitMQ and Elasticsearch orchestration for Zerops. Karakoram provisions and operates Percona Server for MongoDB (PSMDB) with Percona Backup for MongoDB (PBM), RabbitMQ, and Elasticsearch with optional Kibana, Logstash and APM Server across your own Zerops projects. It provides a Go control plane, REST API, karactl CLI and React web UI—without Kubernetes or a hosted coordinator.
You own the infrastructure, credentials, data and recovery procedures. Zerops is the infrastructure backend, not the operator of your databases. Project site: karakoram.dev · Source: github.com/KarakoramDev/Karakoram.
Features
MongoDB
- Replica sets with 1/3/5/7 members, initial-sync-aware scaling/replacement, quorum-aware removal and retained-volume suspend/resume.
- Sharded clusters with config-server and shard replica sets, mongos routers, shard addition and balancer controls.
- S3-compatible PBM logical/physical backups, UTC schedules and count retention, PITR, in-place restore and clone.
- CPU/RAM configuration, persistent disk growth, rolling binary upgrades/restarts and explicit FCV promotion.
- Database users/roles, independently rotatable system accounts, keyfile authentication, generated or supplied TLS certificates and opt-in public TCP access.
RabbitMQ
- RabbitMQ 4.3 clusters with persistent per-node storage and quorum-gated rolling scaling, upgrades, restarts and replacement.
- Vhost, user, permission, topic-permission, policy and operator-policy administration; AMQPS and optional public management.
- S3 definitions backups and restore (no messages or PITR).
Elasticsearch
- Combined-node or dedicated-master topologies, rolling maintenance and shard-draining scale-down.
- Native users, roles and API keys, CA-verified HTTPS, S3 snapshots and restore.
- Optional same-version Kibana, Logstash and APM Server. Review the engine guide's licensing and operating constraints.
Across engines
- Catalog-driven creation, CPU/RAM configuration, persistent disk growth and capability-gated operations.
- Per-member monitoring, authenticated Prometheus output, actor-attributed events/audit activity and operations, logs, local accounts, OIDC, namespace-aware RBAC and owner-scoped API tokens.
- Multi-project namespaces, project-scoped tokens, outbound authenticated relays and permission-gated cross-namespace restore/clone.
Read the limitations before production use. Zerops does not guarantee physical-host anti-affinity, Local Storage is single-host and the control plane has one replica. Healthy voters do not prove independent failure domains. Public replica-set routing does not automatically solve external member discovery. Configure backups and exercise recovery before loading important data.
Quick start on Zerops
Fastest path: the 10-minute quick start installs Karakoram by pasting one YAML into the Zerops dashboard; no checkout, build tools or CLI needed. The steps below deploy from a local checkout instead.
You need an existing Zerops project, an authenticated zcli and a project-scoped Full access integration token. Sudo mode is not required; leave it disabled for least privilege. A sudo-mode token can read every sensitive variable in the project, including database and Karakoram secrets; Karakoram never needs to read them. From a local checkout, import the template in deploy/:
PROJECT_ID='your-project-id'
zcli project service-import deploy/zerops/import-local.yaml -P "$PROJECT_ID"
In the Zerops dashboard, set the new karakoram service's secret KARAKORAM_ZEROPS_TOKEN to your project token. Preserve the generated KARAKORAM_MASTER_KEY and KARAKORAM_ADMIN_PASSWORD; never commit or print secrets. Deploy from the checkout root:
zcli service push karakoram -P "$PROJECT_ID" --setup karakoram \
--zerops-yaml-path zerops.yaml --no-git --disable-logs
zcli service enable-subdomain karakoram -P "$PROJECT_ID"
Open the service's HTTPS subdomain. Sign in as admin with the generated password from its secret variables, complete the required password change, then sign in again. In the create wizard, choose MongoDB, RabbitMQ or Elasticsearch, use an advertised version, keep TLS required and public exposure disabled, and wait for observed readiness. Follow the MongoDB replica-set, RabbitMQ or Elasticsearch guide for engine-specific setup.
See the installation guide for prerequisites, secret handling, custom domains, CLI login and the Git-import alternative using deploy/zerops/import.yaml.
Build from source
Use Go 1.24 or newer, Node 22.6 or newer, npm and Make:
make build-all # build the web UI and both Go executables
make test # Go unit/handler tests
# All Docker-backed integration packages:
go test -tags integration -count=1 -timeout 30m ./...
A Go-only make build without built UI assets serves a “UI not built” page. See UI development, the verification guide and the end-to-end suite guide for additional checks. End-to-end tests run against your own disposable Zerops deployment, create real resources and incur costs.
Documentation index
These guides belong to a complete repository checkout. Keep docs/ beside
api/, ui/ and this root README when copying them: relative links to the
OpenAPI specification, architecture decisions and UI development instructions
are repository paths, not a standalone documentation-bundle layout.
- Quick start, installation, control-plane upgrades, architecture and architecture decisions
- Namespaces and relay lifecycle
- MongoDB: replica sets and sharding
- RabbitMQ clusters, access, TLS and definitions backups
- Elasticsearch and the Elastic Stack: topologies, connections, native access, snapshots and maintenance
- MongoDB: backups, PITR, restore and clone, scaling and upgrades, database users, TLS and access
- Monitoring
- Web UI, RBAC and authentication, REST API, CLI reference
- Day-2 operations and recovery, security and vulnerability reporting, limitations, verification matrix
- Contributing and Code of Conduct
Acknowledgements
Thank you to Percona for Percona Server for MongoDB and Percona Backup for MongoDB. Karakoram installs both from Percona's official package repositories at repo.percona.com. The database engine, replication, backups and point-in-time recovery come from their open-source work; Karakoram coordinates those capabilities rather than reinventing them.
OpenEverest is the inspiration for this project. Originally Percona Everest, it is an Apache-2.0 CNCF Sandbox project whose model of self-hosted, provider-based database orchestration shaped Karakoram: Provider/Instance concepts, version bundles, topology schemas, backup storages, PITR/restore flows and RBAC. Karakoram brings that idea to Zerops rather than Kubernetes. It is an independent implementation; no OpenEverest code or UI is copied into this repository. We are grateful for the ideas and the work that made them tangible.
The name is an homage. Everest is the highest peak; Karakoram is the range that holds K2 and other giants. It is a nod to OpenEverest and to growing beyond a single peak, with room for more engines and backends in the future—not a claim that those are implemented today.
License and trademarks
Karakoram is licensed under the Apache License 2.0; see NOTICE. Dependencies retain their own 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, and Karakoram is independent and is not affiliated with or endorsed by any of 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/elastic
Package elastic renders and supervises secured Elastic Stack node processes.
|
Package elastic renders and supervises secured Elastic Stack node processes. |
|
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. |
|
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. |
|
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/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. |
|
infra/zerops
Package zerops implements Karakoram's Zerops REST infrastructure backend.
|
Package zerops implements Karakoram's Zerops REST infrastructure backend. |
|
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. |
|
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. |
|
relay
Package relay provides authenticated, namespace-scoped TCP tunnels and relay credentials.
|
Package relay provides authenticated, namespace-scoped TCP tunnels and relay credentials. |
|
server
Package server exposes the public API and private, CA-pinned agent configuration endpoint.
|
Package server exposes the public API and private, CA-pinned agent configuration endpoint. |
|
store
Package store provides pure-Go SQLite persistence for Karakoram resources.
|
Package store provides pure-Go SQLite persistence for Karakoram resources. |
|
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. |