Overview

Self-hosted MongoDB orchestration for Zerops. Karakoram provisions and operates Percona Server for MongoDB (PSMDB) and Percona Backup for MongoDB (PBM) inside your own Zerops project. 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

• 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.
• Per-member monitoring, authenticated Prometheus output, events/logs, local accounts, OIDC, RBAC and owner-scoped API tokens.

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

You need an existing Zerops project, an authenticated zcli and a project-scoped Full access integration token. 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. Create a cluster in the UI using an advertised version, keep TLS required and public exposure disabled, and wait for observed readiness.

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 20 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

• Installation, control-plane upgrades, architecture and architecture decisions
• Replica sets and sharding
• 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.