Tales of How OpenEverest is actually built
My own map of the codebase, not a copy of the official docs. Writing it as I understand each piece, so parts of this will get corrected later once I go deeper. If something's wrong here, that's kind of the point of a learning log.
main branch is the v2 developer preview, not what most people run. The production release is on v1.x, and v2 changed some of the core design (v1's DatabaseCluster resource became a more general Instance + pluggable Provider in v2). Everything below is about v2.
what it does, in one paragraph
OpenEverest installs into a Kubernetes cluster and gives you a web UI, a REST API, and a CLI (everestctl) to provision and manage databases on it: creating instances, running backups and restores, watching monitoring. Built the way most serious Kubernetes platforms are: you describe what you want as a Kubernetes object, and a controller running in the background makes the cluster match that.
the shape of the repo
| Directory | What lives there |
|---|---|
cmd/ |
The three actual Go binaries: the API server, the controller manager, and the CLI |
commands/ |
Every everestctl subcommand (backup, restore, instance, auth, and so on), built with Cobra |
internal/server/ |
The HTTP API, built on the echo framework |
internal/controller/ |
The Kubernetes controllers that do the real work |
internal/webhook/ |
Admission webhooks |
pkg/rbac/ |
The permissions engine (casbin) |
api/ |
The Go type definitions for every custom Kubernetes resource (CRD) |
ui/apps/everest/ |
The web app: React, TypeScript, Vite, MUI |
docs/ |
Project docs, including a genuinely good set of UI architecture docs under docs/ui/architecture/ |
how a request turns into a running database
you never talk to kubernetes directly. you go through the cli or ui, the api server checks who you are and validates the request, kubernetes stores that as the desired state, and a controller in the background makes it real.
controllers i’ve actually read so far, in internal/controller/:
- BackupReconciler: runs an on-demand backup by creating a Kubernetes Job plus the RBAC it needs.
- RestoreReconciler: same idea in reverse, restoring from a
Backupor a point-in-time source. - BackupStorageReconciler: manages where backups get stored (an S3-compatible target, say).
- MonitoringConfigReconciler: wires up PMM monitoring for an instance.
- PluginReconciler and InstalledExtensionReconciler: install and track plugins. how OpenEverest adds functionality without baking it into core.
the part that’s actually well designed: the api handler chain
Every API request goes through three handlers, each one implementing the same tiny interface (SetNext, then handle-or-pass-along), chained: validate the request shape, check permissions, then actually talk to Kubernetes.
internal/server/handlers/: validation/, rbac/, k8s/. each one only knows about the next one in line, not the whole chain.
Clean, textbook chain-of-responsibility. Honestly the easiest part of the server to understand, exactly because each piece only does one job and doesn’t care what happens after.
files worth reading if you’re new here
cmd/cli/main.go: about as small and plain as a Gomain()gets.internal/server/handlers/handler.go: the interface behind the diagram above.internal/controller/backup/backupstorage_controller.go: the simplest controller, good first reconciler to read.docs/ui/architecture/: the maintainers already wrote solid frontend architecture docs with diagrams. read those directly instead of trusting me to re-explain it.
sources: read directly from /README.md, go.mod, cmd/, internal/server/, internal/controller/, api/, and docs/ui/architecture/ in the repo. nothing here was run, only read, so if the code’s moved on since, trust the repo over this page.