Skip to content
SHC Docs

Tech stack

Layer 2. Core. Core

SHC is a Go CLI and a daemon. A deployment is the running unit. The CLI (shc) and the daemon (shcd) are two binaries built from cmd/shc/ and cmd/shcd/; the rest of the code is top-level; there is no internal/ directory, and the same layer names (core/, daemon/, modules/, subsystems/) exist in both repos. The open core lives in ce, consumed here as a pinned Go module; this repo holds the enterprise half of each layer. Paths below are written ce <path> or shc <path> wherever it matters. This document defines the technical choices for all aspects of the codebase.


ComponentChoiceNotes
LanguageGo 1.25+Compiled binaries, pure Go (CGO_ENABLED=0)
Build toolchainasdf + gomake build produces bin/shc + bin/shcd
Bundled binariesrqlitedFetched to vendor/rqlite/ by make vendor/rqlite
ComponentChoiceNotes
CLI Frameworkspf13/cobraStandard Go command tree
Terminal Outputcharmbracelet/lipgloss + bubbleteaStyled text + Bubbletea TUI for shc hud
Shell Completioncobra-generatedBash/Zsh/Fish completion support
ComponentChoiceNotes
HTTP Routergo-chiLightweight chi router + middleware
HTTP Servernet/http with chiUDS + TCP listeners served from one daemon
Validationgo-playground/validator/v10validate: struct tags + custom validators
ComponentChoiceNotes
Lifecycle Managerce subsystems/lifecycleCentral orchestrator for all server subsystems
Subsystem Protocollifecycle.SubsystemUniform interface: Name(), Start(), Stop(), Health()
Fail-FastsystemdService crashes bring down server; systemd restarts
Leader Electionraft (leader_hub)The raft leader id (rqlited) drives the leader signal

See daemon-manager for details.

ComponentChoiceNotes
DatabaseSQLite / rqlitePlain file + WAL at {state}/shc.db single-node; raft-replicated rqlite in clusters
Drivermodernc.org/sqlite (pure Go)Registered as the sqlite sql driver; the pool swaps to shc-rqlite at boot when {state}/engine.json exists
Distributedrqlite (external rqlited process)Supervised by the daemon (shc core/rqlited); SQLite with Raft consensus
Query layerent ORM + per-module reposent-generated client (ce ent/) over the shared db pool; one *StackRepo / *NodeRepo per module wraps it
MigrationsAtlas (ariga/atlas)One first file under ce migrations/, then migrations appended with make migrate NAME=<slug>; integrity hash in atlas.sum, released lines held in core/db/released.sum

ent/ and migrations/ live in the ce repo, not here; make migrate in this repo is a signpost that prints where they went and exits non-zero. The daemon still applies the migration at startup from the embedded SQL, so there is nothing to run on this side.

Database modes:

  • Single-node: plain SQLite (no raft, zero coordination)
  • Cluster: external rqlited raft engine (automatic promotion when the first shc node join enrolls)
ComponentChoiceNotes
Node runtimedocker, podman, incus, appleOne runtime per node
Runtime executionCompose CLI, incus-compose or Apple’s container CLIAll four executors linked into shcd
Cluster staterqlitedRaft on mesh0
Container fabricshc0WireGuard and nftables on Linux

Sources: CE daemon/imports.go, core/hostplat and modules/fabric. See Runtime support.


The ce repo carries the open core: the registries, the base modules, the schema:

ce/
├── cmd/{shc,shcd}/ # the reference mains
├── core/ # cross-module primitives
│ ├── coded/ # X######CCCCCC error machinery
│ ├── api/ # chi helpers, manifest, auth, SSE
│ ├── db/ # *db.Pool, migration runner, scan helpers
│ ├── log/ # typed slog wrapper + audit
│ ├── paths/ # XDG-aware filesystem layout
│ ├── registry/ # central router + command + error + cron registries
│ └── ... # ~35 packages in all
├── daemon/ # daemon boot + composition root
├── modules/ # base feature modules (one per domain)
│ ├── app/ backup/ vault/ config/ logs/ shell/ …
│ └── {module}/commands/ # that module's cobra subcommands
├── subsystems/
│ ├── lifecycle/ # supervisor + resolver
│ └── impl/ # config loader, event bus, queue, cron runner,
│ # http + internal-API listeners, reconcilers, ...
├── ent/ # ent schema + generated client
└── migrations/ # Atlas SQL migrations + atlas.sum

This repo pins that module and adds the enterprise half of the same layers, plus the out-of-process components:

shc/
├── cmd/
│ ├── shc/ # CLI binary (cobra root)
│ ├── shcd/ # daemon binary
│ └── shc-x9s/ validate-templates/ verify-image-pins/ verify-addon-freshness/
├── cli/ # CLI composition: build shape, license + quota clients
├── core/ # db, rqlited supervisor, otel boot, collector config, ...
├── daemon/wiring/ # the wiring this repo contributes to the composition root
├── modules/ # cluster, license, quota, node, tenant, user, hud, ...
├── subsystems/ # rqlite engine, leader elector, collectors (flat, no impl/)
├── pkg/ # apiclient, appimages, scrub
├── apps/ # app catalog; fixtures/ standalone/ enterprise/ bucket the rest
├── collector/ forward-auth/ traefik/ keycloak/ license-broker/ # out-of-process components
├── terraform/ # provider + modules + examples
├── website/ # Astro + Starlight docs and marketing site
├── tests/ # own Go module: unit/, integration/, parity/, e2e/, proxmox/
└── docs/ # Documentation

collector/processor/*, forward-auth/, traefik/plugin/, traefik/render/, terraform/provider/ and tests/ are each their own Go module.

Both repos’ modules/{module}/ directories follow the same structure, so a module reads the same whether it is a base module in ce or an enterprise module here:

modules/{module}/
├── service.go # *Service struct + methods (business logic)
├── router.go # HTTP routes via chi
├── types.go # request/response Go structs + validate tags
├── errors.go # X######CCCCCC factories + Spec slice + init()
├── events.go # event handler registrations (where applicable)
├── register.go # init() side-effects (router builder, command builder, runtime singleton)
├── service_test.go # unit tests against fakes
├── router_test.go
└── commands/ # cobra subcommand surface (if module exposes CLI verbs)
├── main.go
└── ...

ToolPurposeConfig
gofmtCode formatting(canonical)
golangci-lintLint suite (forbidigo, gocritic, staticcheck, errcheck, …).golangci.yml
shfmtShell-script formatting (apps, tests)make format
  • forbidigo rejects errors.New and fmt.Errorf outside test files: every error path must surface a *coded.CodedError.
  • staticcheck, errcheck, unused, gocritic, goimports all on.
  • Tests are exempt from forbidigo’s stricter rules but not from gofmt/unused/staticcheck.

ToolPurpose
testing stdlibTest runner
testing.TB.ContextPer-test cancellable context
httptestIn-process HTTP server for handler tests
Hand-rolled fakesCross-module seam stand-ins
Terminal window
# Run all tests
make test/unit
# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html
# Run in parallel (default: GOMAXPROCS); disable with -p=1
go test -p=1 ./...
# Race detector (integration suite turns this on by default)
go test -race ./...
ToolPurpose
BatsBash Automated Testing System
ProxmoxMulti-node VM e2e

SurfaceComponent
Logstyped wrapper in core/log/; WARN+ requires a *coded.CodedError (raw slog.Warn/slog.Error are lint-banned); structured JSON + audit class + event-bus fan-out
MetricsOpenTelemetry meters + scoped registries (modules/metrics/)
TracingOpenTelemetry traces with W3C traceparent propagation
EventsInternal event bus (modules/events/) + SSE for clients
// modules/metrics/definitions.go: sample shapes
backupTotal := svc.RecordCounter(ctx, "shc_backup_total", 1)
activeStacks := svc.RecordGauge(ctx, "shc_active_stacks", float64(n))
opDuration := svc.RecordHistogram(ctx, "shc_operation_duration_seconds", elapsed.Seconds())

Runtime dependencies (selected, see go.mod for the full list):

modernc.org/sqlite // pure-Go sqlite driver
github.com/spf13/cobra // CLI framework
github.com/go-chi/chi/v5 // HTTP router
github.com/go-playground/validator/v10 // input validation
go.opentelemetry.io/otel // metrics + tracing
github.com/charmbracelet/bubbletea // HUD TUI
github.com/charmbracelet/lipgloss // terminal styling
ariga.io/atlas // migrations
github.com/moby/docker // docker SDK
go.yaml.in/yaml/v3 // YAML parsing

Dev tooling lives in go.mod build constraints; gofmt, golangci-lint, and bats are installed via asdf at make prepare.


MethodCommandUse case
.deb/.rpm/.apkmake package && sudo {dpkg,rpm,apk} -i dist/shc_*_linux_amd64.<fmt>Production
Direct Installmake installDevelopment/testing

Package structure (built by goreleaser/nfpm)

Section titled “Package structure (built by goreleaser/nfpm)”
ComponentPath / approach
Build SystemGoReleaser + nfpm (.goreleaser.yaml)
Go binaries/usr/bin/shc, /usr/bin/shcd (static, CGO_ENABLED=0)
Bundled rqlited/usr/lib/shc/bin/rqlited (spawned by the daemon in cluster mode)
systemd unit/usr/lib/systemd/system/shc.service (static, FHS paths)
Group/Dirssystemd-sysusers (shc.sysusers.conf), systemd-tmpfiles (shc.tmpfiles.conf)
Scriptletsscripts/{postinstall,preremove,postremove}.sh

These technologies are explicitly not used:

TechnologyReason
Vue/SvelteReact is the one UI framework in the tree: see below
TailwindThe CSS that exists is hand-written; no utility framework
PostgreSQL/MySQLSQLite/rqlite is sufficient
RedisNot needed for current scope
KubernetesOne runtime per node: docker, podman, incus, apple
GraphQLREST API is simpler
Generated mocksHand-rolled fakes are cheaper to maintain

The control plane is Go. The repo also carries frontend code and components in other languages:

SurfaceWhat it is
apps/console/The SHC web console, a multiplatform.one app (React + Tamagui), shipping web, iOS, Android and GTK4 from one codebase
apps/marketplace/The app-store front end, same stack
website/Astro 7 + Starlight documentation and marketing site: .astro, TypeScript, .mjs build scripts, hand-written CSS, a pnpm workspace, Playwright
traefik/plugin/Yaegi-interpreted Traefik middleware that injects an app-launcher menu: it writes an inline <style> block and an inline <script> into HTML responses (menu.go)
keycloak/A Keycloak SPI in Java (Maven), plus the shc admin theme: keycloak/themes/shc/admin/resources/css/shc-admin.css
apps/*/Apps carry whatever their upstream needs (e.g. apps/security/ivatar/login.html)

The frontends are named in FRONTEND_APPS in the Makefile and are not catalogue apps: see app buckets.

Why a console does not cost the CLI-first principle

Section titled “Why a console does not cost the CLI-first principle”

The console is a client of the same API the CLI calls. It has no private endpoint, no back door into the daemon, and no capability the command line lacks: both speak /api/method/shc.* and /api/resource/<DocType> over the same auth. Adding a screen cannot add a feature; the RPC has to exist first, which means it is scriptable before it is clickable.

That ordering is the whole guarantee, and it is why the console is a addition rather than a reversal. The failure mode to watch for is the opposite order: a capability that reaches the console without an RPC behind it. If you ever find one, the defect is the missing RPC.

React is here because the console consumes multiplatform.one, which targets web, iOS, Android, GTK4 and VS Code from one component tree. That is the reason it earns its place: five surfaces, one codebase, not because a web page needed a framework.