The shared UI design contract and token source for Panel and Cloud are in docs/design-system. Existing pages are being migrated; this architecture overview does not imply complete adoption.
Carbon Panel is a modern, enterprise-grade Minecraft server orchestration platform and intelligent TCP reverse proxy. It couples a containerized backend written in Go with an IBM Carbon Design System web interface engineered in SvelteKit 2 and Svelte 5.
- Deterministic Isolation: Every game server runs as an independent, sandboxed OCI/Docker container. No runtime dependencies, libraries, or JVM artifacts are shared across server environments.
- Zero-Friction Ingress: Single-port TCP multiplexing (
25565) enables hosting unlimited server domains without requiring port forwarding, manual port mapping, or multi-port firewall rules. - Rigorous Design Fidelity: The user interface strictly implements the IBM Carbon Design System (v11 Gray 100 theme) with 0px sharp geometry, IBM Plex typography, and 2x grid alignment.
- Contract-Driven APIs: All communication between frontend, backend, and CLI utilities is defined through Protocol Buffers and Connect-RPC schemas (
proto/carbonpanel/v1). - Unified Developer Experience: Live hotloading with Go Air and Bun/Vite HMR allows instant cross-stack development.
flowchart TB
subgraph ClientLayer ["Client & Player Layer"]
MC["Minecraft Game Clients"]
Browser["Modern Web Browsers"]
CLI["API Clients & CLI"]
end
subgraph IngressLayer ["Ingress & Routing Layer"]
Proxy["TCP Reverse Proxy (:25565)\n(Handshake Packet Inspector)"]
WebGateway["Connect-RPC & HTTP Gateway (:8080)"]
WSHub["WebSocket Streaming Hub (:8080/ws)"]
end
subgraph DaemonLayer ["Carbon Panel Core Daemon (Go 1.24+)"]
RPC["RPC Handler Engine\n(Server, Modpack, Auth, Config)"]
Router["Dynamic Route Registry\n(Virtual Host Mapping)"]
Scheduler["Cron & Task Scheduler\n(Maintenance & Backups)"]
PackwizMgr["Packwiz & Modpack Engine\n(CurseForge & Modrinth)"]
RCONMgr["RCON & Log Ring Buffer"]
AuthRBAC["Auth & RBAC Subsystem\n(JWT, OIDC, Permissions)"]
DB["SQLite Storage Engine\n(Embedded Migrations)"]
end
subgraph ContainerLayer ["Container Infrastructure (Docker Engine)"]
Sock["/var/run/docker.sock"]
C1["Container: Survival (Paper)"]
C2["Container: Modded (Fabric)"]
C3["Container: Lobby (Velocity)"]
Sidecars["Container: Geyser / Sidecars"]
end
MC -->|TCP :25565 Handshake| Proxy
Browser -->|HTTP/REST/Connect| WebGateway
Browser -->|Real-Time Logs| WSHub
CLI -->|gRPC / Connect| WebGateway
Proxy -->|Route Lookup| Router
Proxy -->|Internal Bridge :25565..| C1
Proxy -->|Internal Bridge :25565..| C2
Proxy -->|Internal Bridge :25565..| C3
WebGateway --> RPC
WSHub --> RCONMgr
RPC --> AuthRBAC
RPC --> DB
RPC --> PackwizMgr
RPC --> Scheduler
RPC --> Sock
Sock --> C1
Sock --> C2
Sock --> C3
Sock --> Sidecars
The frontend application in web/carbon-panel is built using SvelteKit 2, Svelte 5 Runes, Tailwind CSS v4, and custom IBM Carbon Design System components.
- Svelte 5 Runes Mode: Reactivity is implemented exclusively using Svelte 5 runes (
$state,$derived,$effect,$props, and{#snippet}) eliminating legacy Svelte 3/4 stores and mutable reactive declarations ($: ...). - Tooling & Runtime: Managed with Bun for fast package installation, lockfile resolution (
bun.lock), and local execution. - Build Target: Compiled via
@sveltejs/adapter-staticfor zero-overhead embedding directly into the Go backend binary viaembed.FS.
graph TD
Tokens["Carbon Gray 100 Tokens\n(#161616, #262626, #393939, #0f62fe)"]
Tailwind["Tailwind CSS v4 Engine\n(@theme inline, @layer utilities)"]
Primitives["Custom Carbon Primitives\n($lib/components/carbon/*)"]
UI["Core UI Adapters\n($lib/components/ui/*)"]
Views["Carbon View Surfaces\n(Dashboard, Servers, Studio, Settings)"]
Tokens --> Tailwind
Tailwind --> Primitives
Tailwind --> UI
Primitives --> Views
UI --> Views
- Zero Border Radius: In accordance with IBM Carbon v11, every UI element enforces sharp, rectangular geometry (
--radius: 0px,rounded-none). Rounded pills, soft bubbles, and floating card dropshadows are prohibited. - Color Palette (Carbon Gray 100 Dark Theme):
- Background (
--background):#161616 - Layer 01 / Tiles (
--card):#262626 - Layer 02 / Elevated Surfaces (
--popover):#393939 - Layer 03 / Active Hover (
--accent):#353535 - Interactive 01 / Primary Accent (
--primary):#0f62fe(IBM Blue 60) - Support Danger (
--destructive):#da1e28(Carbon Red 60) - Support Success:
#24a148(Carbon Green 50) - Support Warning:
#f1c21b(Carbon Yellow 30)
- Background (
- Typography: IBM Plex Sans for UI controls and IBM Plex Mono for code, metrics, ports, and console output.
To avoid CSS specificity regressions, all styling is strictly compiled inside Tailwind CSS v4's @layer utilities and @theme inline. Monolithic legacy CSS bundles (such as unlayered g100.css) are excluded to prevent unlayered CSS resets from overriding utility classes.
CarbonShell.svelte: 48px fixed top header with brand logo, cluster indicator, and 64-column collapsible navigation drawer with active blue indicator.CarbonTile.svelte: Sharp#262626surface with1px solid #393939border, supporting interactive hover transitions.CarbonButton.svelte: Sharp button with primary (#0f62fe), secondary (#393939), and destructive (#da1e28) variants.CarbonTag.svelte: High-contrast, sharp status indicators (Green for Running, Gray for Stopped, Blue for Starting, Red for Error).CarbonDataTable.svelte: Structured data table with#393939headers,#353535row hover states, and integrated action toolbars.CarbonTabs.svelte: Flat horizontal navigation with 2px#0f62feactive underline indicators.CarbonPageHeader.svelte: Canonical page header: 2xl light title, optional status tag, small#8d8d8ddescription, right-aligned action row, 1px bottom rule, and a responsive single-column fallback belowsm.
- Every primary route starts with one
CarbonPageHeader; routes must not hand-roll title/description/action rows. This keeps title scale, header rule and action placement identical across the app. CarbonShellowns the page gutter (p-4 md:p-6). Route roots must not add anotherp-6/p-8; sections own their internal padding only.CarbonButtoncentres its icon and label with a fixed gap and never wraps the label. Icon-only buttons inherit the requested size rather than forcing a 40px square.- A missing metric is rendered as unavailable (
—/IDLE/AWAITING SAMPLE), never fabricated. This is a product rule as well as a visual one.
The backend daemon in cmd/carbon-panel coordinates several loosely-coupled subsystems:
carbon-panel/
├── cmd/
│ ├── carbon-panel/ # Main server daemon entrypoint
│ ├── geyser/ # Bedrock translation sidecar entrypoint
│ └── status/ # CLI health probe utility
├── internal/
│ ├── alias/ # DNS and host alias resolution
│ ├── auth/ # Token issue, validation, OIDC, and password hashing
│ ├── cache/ # In-memory LRU and object caching
│ ├── command/ # Server command queue and executor
│ ├── config/ # YAML config loader and viper schema bindings
│ ├── db/ # SQLite connection pool and schema migrations
│ ├── docker/ # Docker client wrapper, container lifecycle & health
│ ├── events/ # Asynchronous in-memory pub-sub event bus
│ ├── indexers/ # CurseForge, Modrinth, and loader metadata scrapers
│ ├── metrics/ # Telemetry aggregator, TPS calculators, CPU/RAM stats
│ ├── minecraft/ # Protocol handshake decoders & server.properties parser
│ ├── module/ # Extensible sidecar module manager
│ ├── packwiz/ # Modpack compilation, loader migration & manifest sync
│ ├── proxy/ # Multi-tenant Minecraft TCP reverse proxy
│ ├── rbac/ # Role definitions and resource permission checks
│ ├── rcon/ # TCP RCON client for interactive server console
│ ├── rpc/ # Connect-RPC service implementation handlers
│ ├── scheduler/ # Automated cron task scheduler
│ ├── snapshot/ # Backup archive and restore manager
│ ├── webhook/ # Discord and HTTP alert dispatchers
│ └── ws/ # Real-time WebSocket terminal and event hub
└── pkg/ # Shared utility libraries (logger, files, download)
Minecraft clients connect over TCP using the Minecraft Protocol handshake. Standard HTTP reverse proxies (like NGINX or Traefik in HTTP mode) cannot parse Minecraft packets.
Carbon Panel implements a high-performance raw TCP proxy:
- Handshake Parsing: When a client initiates a connection on port
25565, the proxy reads the initial variable-lengthHandshakepacket (0x00). - Server Address Extraction: The packet contains the exact hostname string entered by the player in their Minecraft client (e.g.,
survival.myserver.com). - Route Lookup: The proxy queries
internal/proxy.Registryto match the hostname against configured server routing rules. - TCP Splice / Tunneling: Once the target backend container port is resolved, the proxy opens an upstream TCP socket and transparently bidirectional-pipes packets with minimal latency.
sequenceDiagram
autonumber
actor Player as Minecraft Client
participant Proxy as Carbon Panel Proxy (:25565)
participant Router as Route Registry
participant Container as Docker Container (Server)
Player->>Proxy: TCP SYN & Connect
Player->>Proxy: Minecraft Handshake Packet (0x00)
Note over Proxy: Extracts Hostname (e.g. "skyblock.lan")
Proxy->>Router: LookupRoute("skyblock.lan")
Router-->>Proxy: Backend: 127.0.0.1:25571 (Server ID: abc-123)
Proxy->>Container: TCP Connect (127.0.0.1:25571)
Proxy->>Container: Replay Handshake Packet
loop Bidirectional Streaming
Player<->Proxy: Game Traffic (Raw TCP)
Proxy<->Container: Game Traffic (Raw TCP)
end
Carbon Panel uses the official Docker Engine API (github.com/docker/docker/client) to orchestrate container lifecycles:
- Base Images: Utilizes optimized
itzg/minecraft-servermulti-architecture images. - Volume Binding: Server directories are mounted into the container at
/data, isolating world saves, configs, and plugins. - Resource Constraints: Dynamically applies CPU quotas (
NanoCPUs) and memory limits (Memory) defined per server. - JVM Optimization: Automatically applies Aikar's optimized G1GC garbage collection flags based on allocated RAM.
The modpack engine enables full modpack authoring and distribution:
- Format Agnostic: Imports CurseForge zip manifests, Modrinth
.mrpackarchives, and Packwizpack.tomlprojects. - Version Matrix Engine: Evaluates loader compatibility (Fabric, Forge, NeoForge, Quilt) against Minecraft target versions.
- Staging & Sync: Changes to mods and override configurations are staged into an ephemeral directory and synchronized to the server container without destructive overwrites.
Carbon Panel supports a distributed, multi-node topology. The architecture distinguishes the control plane (users, roles, servers, tasks, node registration — the system of record) from the data plane (Minecraft traffic routing), and treats them very differently with respect to placement and availability:
- Control plane — single controller with SQLite: the system-of-record database (users, roles, servers, tasks, node registration) remains a single SQLite file on the controller node (DESIGN.md §6). The
20260307_001_multinode_default_nodemigration ininternal/db/migrations.gobackfills anode_idcolumn onservers/modulesso control-plane records can be bound to a specific remote node. - Remote nodes are Docker Engine API endpoints:
internal/docker/pool.go'sClientPooldials remote Docker daemons pernode_id, with TLS client key/cert support, so server/module containers can be scheduled onto any registered node. Node registration and health are modeled bynode.protoand served byNodeService. - Proxy routing sync via Valkey/Dragonfly:
internal/proxy/valkey_sync.goimplements a Valkey/Dragonfly-backed (Redis RESP protocol) pub/sub + KV layer so the proxy route table stays consistent across nodes without round-tripping through SQLite. This means the Minecraft data plane can keep routing traffic even while control-plane writes are unavailable.
- Single point of failure: the controller's SQLite file is a SPOF for the entire cluster's control plane. Losing it (or its disk) takes down management of every node, even though the Valkey-synced proxy layer could in principle keep routing traffic.
- Write scaling ceiling: SQLite's single-writer model caps concurrent control-plane writes (server CRUD, task scheduling, RBAC changes) as node/server count grows.
- Deliberate decision (open): if multi-controller failover is a real near-term goal,
rqlite/dqlite(Raft-replicated SQLite) are the minimal-change options, withLitestreamcontinuous backup to object storage as a cheaper way to bound data loss from the existing single-writer setup; a full move to PostgreSQL is the more conventional path only if genuine multi-writer horizontal write scaling is needed. This decision is intentionally left open and should be revisited before controller HA becomes a requirement.
Five internal seams concentrate node-to-daemon resolution, lifecycle ownership, idle-power policy, proxy route planning, and world-data snapshot/restore. Call sites must use these modules rather than re-implementing the same rules. The ADRs are authoritative for rationale; this table is the package map.
| Seam | Package path | Owns | ADR |
|---|---|---|---|
| Locator | internal/docker/locator.go |
One node-addressed adapter from a logical node to a Docker client or command executor, with typed fail-closed errors (ErrUnknownNode, ErrNoClient). Never (nil, nil). |
0004-docker-locator |
| Lifecycle handle | internal/docker/transition.go |
One Transition claim: TryBeginServerTransition returns the handle; only that handle can Release(), and release is idempotent. |
0005-lifecycle-transitions |
| Idle-power module | internal/docker/idle.go |
Shared idle tracker, mode data and sweep runner. Freeze and deep sleep are idleMode values, not a second manager copy. |
0006-idle-modes-are-data |
| Route PlanFor | internal/proxy/plan.go |
Pure PlanFor over already-observed server, node and listener views. The proxy manager applies plans; it does not encode route policy under the lock. |
0004-proxy-route-plans |
| Worldstore | internal/worldstore |
Quiesce, manifest snapshot, backup and journaled restore of world data. Default scheduled backups and restores use this seam. | 0004-world-data-seam |
internal/docscheck fails CI when a path in this table is renamed or deleted, or when DESIGN.md drops the citation.
Carbon Panel standardizes on Protocol Buffers v3 and Connect-RPC. All schema files reside in proto/carbonpanel/v1/.
proto/carbonpanel/v1/
├── auth.proto # Login, registration, token refresh, recovery key
├── common.proto # Enums (ServerStatus), User, Role, Permission entities
├── config.proto # Global and server configuration properties
├── event.proto # System event stream schemas
├── file.proto # File manager tree, read, write, and bulk operations
├── minecraft.proto # Minecraft metadata, versions, and player models
├── mod.proto # Mod search, install, and dependency models
├── modpack.proto # Packwiz project models and import/export specs
├── module.proto # Sidecar module descriptors
├── node.proto # Multi-node host clustering models
├── proxy.proto # Hostname route definitions
├── role.proto # RBAC role definitions
├── server.proto # Server CRUD, start, stop, restart, stats, logs
├── support.proto # Diagnostics and bug reporting
├── task.proto # Scheduled cron jobs and tasks
├── upload.proto # Chunked binary file upload contracts
├── user.proto # User management operations
└── websocket.proto # WebSocket envelope definitions
Persistence is handled by SQLite located at data/carbon-panel.db (or a custom path via storage.data_dir / CARBONPANEL_STORAGE_DATA_DIR).
erDiagram
USERS ||--o{ SESSIONS : has
USERS }o--o{ ROLES : assigned
ROLES ||--o{ PERMISSIONS : grants
SERVERS ||--o{ ROUTES : exposes
SERVERS ||--o{ TASKS : schedules
SERVERS ||--o{ SNAPSHOTS : owns
USERS {
string id PK
string username
string email
string password_hash
string auth_provider
boolean is_active
datetime last_login
}
SESSIONS {
string id PK
string user_id FK
string token
datetime expires_at
}
SERVERS {
string id PK
string name
string loader_type
string mc_version
int memory_limit
int cpu_limit
string container_id
string status
}
ROUTES {
string id PK
string server_id FK
string hostname
int target_port
boolean active
}
TASKS {
string id PK
string server_id FK
string cron_expression
string action
datetime next_run
}
- The host
/var/run/docker.sockis mounted into the Carbon Panel daemon container. - Container creation enforces strict resource isolation (
NanoCPUs, memory hard limits). - Server containers run non-root users inside the container where supported.
- Local Authentication: Argon2id/bcrypt hashed passwords with optional invite codes.
- OIDC / SSO: Integrates with external Identity Providers (Keycloak, Authentik, Okta, GitHub).
- Session Tokens: Stateless signed JWTs with expiration, stored in browser
localStorage. - Granular RBAC:
*.*.*: Super Admin (complete system control).server.*.<id>: Operator permission restricted to specific game server IDs.server.view.*: Read-only telemetry and log viewer.
- Recovery Key: On first-time setup or system initialization, an offline recovery key is generated and hashed into the database, allowing admin password resets if authentication becomes inaccessible.
flowchart LR
Commit["Git Push / PR"] --> CI["GitHub Actions CI (ci.yml)"]
subgraph CI ["Automated CI Suite"]
BE["Backend Test Suite\n(Go 1.25, full go test ./... + vet + lint)"]
FE["Frontend Quality Gate\n(Bun, check + unit tests + Vite build)"]
end
Commit -->|"push to main / tag v*"| CD["Docker Hub CD (cd.yml)"]
subgraph CD ["Automated Image Publishing"]
QEMU["Set up QEMU"]
Buildx["Buildx Multi-Arch\n(linux/amd64, linux/arm64)"]
Push["Push to Docker Hub\n(atharvnaphade/carbonpanel)"]
end
Tag["Git Tag v*"] --> REL["Release Workflow (release.yml)"]
subgraph REL ["Binary + Docker Release"]
Bin["Cross-compiled binaries\n(linux/darwin/windows, Go 1.24.5)"]
RelDocker["Docker image + GitHub Release + Discord notify"]
end
ci.yml— Backend Test Suite: runs on every push tomainand every PR intomainagainst Go 1.25.0. It runs the full backend test suite (make test, i.e.go test ./...), so CI, the Makefile, and local dev all agree on what "the test suite" means. It also runsgo vet ./...andgolangci-lint(scoped to new/changed code viaonly-new-issues, since the codebase has a pre-existing baseline of findings that are out of scope to fix en masse).ci.yml— Proto Lint: runsbuf lintagainst the proto schemas.ci.yml— Frontend Quality Gate: runsbun install --frozen-lockfile,bun run check(SvelteKit/TS type diagnostics),bun run test(Bun's built-in test runner oversrc/**/*.test.ts), andbun run build(production Vite build).cd.yml— Docker Hub CD: builds and pushes a multi-arch (linux/amd64,linux/arm64) image via Buildx with GHA layer caching. For pushes tomainit now triggers onworkflow_runofci.yml(only when the CI run was a push tomainthat succeeded), so a broken:latestimage can no longer be published from a commit that failed CI. Tag pushes (v*) and manualworkflow_dispatchstill publish directly.release.yml— Tag-triggered Release: onv*tags, generates proto artifacts, builds the frontend, cross-compiles binaries for linux/darwin/windows (amd64/arm64) using Go 1.25.0, builds/pushes a Docker image, cuts a GitHub Release, and posts a Discord notification.- Go version: a single version — Go 1.25.0 — is pinned across
go.mod,ci.yml, andrelease.yml, so CI, the module directive, and release binaries all use the same language/stdlib version.
A unified development environment is configured to eliminate manual rebuild cycles:
| Layer | Technology | Tool | Port | Hotloading Mechanism |
|---|---|---|---|---|
| Frontend | SvelteKit / Tailwind | Vite 7 | 5174 |
Vite Hot Module Replacement (HMR) with automatic reverse proxy to :8080 |
| Backend | Go 1.24 | Air (.air.toml) |
8080 |
File-system watcher triggers automatic recompilation to ./tmp/carbon-panel-dev |
| Orchestrator | TypeScript | scripts/dev.ts |
— | Concurrently spawns Air and Vite with unified stdout/stderr logging and signal handling |
To launch the hotloading development environment:
bun run devAccessible at:
- Web Application:
http://localhost:5174 - Backend API / RPC:
http://localhost:8080
Added by an independent architecture audit, 2026-09. This section reflects a point-in-time review of the code under internal/ and .github/workflows/ on main. A follow-up resolution pass (2026-09) addressed most of the findings; the current status of each is summarized in §10.1.1 Resolution status and marked inline ([Resolved] / [Open]) on each finding below.
| # | Finding | Severity | Status |
|---|---|---|---|
| 1 | RBAC route-table fail-open for unregistered procedures | high | Resolved — authInterceptor now fails closed (deny-by-default), including a nil-enforcer path; regression tests in internal/rpc/server_test.go; a procedure-coverage gate in internal/rbac/mapping_test.go asserts every registered procedure maps to exactly one table. |
| 2 | DockerOverrides passes capabilities/bind-mounts/AppArmor straight to Docker |
high | Resolved — ValidateDockerOverrides + IsPrivilegedDockerOverride gate dangerous fields behind the servers/manage_docker_privileged action, with tests in internal/docker/hardening_test.go. |
| 3 | Multi-node clustering keeps a single SQLite system-of-record; undocumented | medium | Resolved (documented) — new §4.4 Multi-Node Clustering & Cluster Control Plane describes the model and the open HA decision. |
| 4 | CI validates a small fraction of the backend, no Go linter | medium | Resolved — ci.yml now runs go test ./..., go vet, and golangci-lint. |
| 5 | Frontend has no automated test coverage | medium | Resolved (baseline) — frontend now has a bun test script wired into CI with unit tests under src/lib/utils/*.test.ts; component-level coverage remains a future enhancement. |
| 6 | CD can push a main image independently of CI result |
low | Resolved — cd.yml now publishes from main only after ci.yml succeeds (via workflow_run). |
1. RBAC's route-table is fail-open for unregistered procedures (high severity). [Resolved]
internal/rpc/server.go's authInterceptor (around line 315) checks a procedure against three maps in sequence: rbac.PublicProcedures, rbac.AuthenticatedOnlyProcedures, then rbac.ProcedurePermissions (defined in internal/rbac/mapping.go). If a procedure string is present in none of the three, the interceptor authenticates the caller and then falls straight through to next(ctx, req) — no resource/action check is performed at all. Concretely: any new Connect-RPC method added to a .proto file and wired into a handler is reachable by any authenticated user, regardless of role, until someone remembers to add a matching entry to ProcedurePermissions. There is no test in the (zero-coverage) internal/rbac package that asserts every registered procedure has a permission entry, so this can regress silently. This is the opposite of the "deny by default, allow what you recognize" posture generally recommended for RPC authorization interceptors — see the fail-closed pattern used by connect-rpc authorization libraries such as connectrpc-authz-go and rbacconnect (pkg.go.dev), and the general principle that the risk here is a handler being "ungated, not denied" when a permission entry is missing.
- The route-table approach (a hand-maintained Go map keyed by procedure path string) is also a maintainability risk independent of the fail-open bug: procedure names are free-form strings with no compile-time link back to the generated Connect service interfaces, so a typo or a renamed RPC silently drops out of enforcement rather than failing to build.
2. DockerOverrides lets scoped operators pass capabilities, bind mounts, and AppArmor overrides straight to the Docker Engine API (high severity). [Resolved]
internal/docker/client.go's ApplyOverrides (around line 276) applies overrides.GetCapAdd(), overrides.GetVolumes() (including arbitrary host bind-mount sources/targets), overrides.GetDevices(), and overrides.GetSecurityOpt() (which can include apparmor:unconfined) verbatim onto the container.HostConfig used to create a per-server container, with no allowlist, denylist, or validation. DockerOverrides is reachable through ConfigService/UpdateServerConfig, which RBAC scopes to server_config.update.<server_id> — i.e. exactly the kind of narrowly-scoped, single-server "operator" role the RBAC model (DESIGN.md §7.2) is designed to support. In the current implementation, an operator scoped to one server can potentially request CAP_SYS_ADMIN/SYS_PTRACE, mount the host filesystem into their container, or disable AppArmor confinement for it — any of which are well-documented container-breakout primitives. Combined with the fact that the Carbon Panel daemon itself holds a mounted /var/run/docker.sock (DESIGN.md §7.1), a breakout from a single scoped operator's container reaches a process with full Docker Engine API access, and from there the host. The blast radius of a single compromised or malicious per-server operator is therefore effectively "the whole host and every other tenant's server," which is disproportionate to the permission they were granted. internal/docker has 8 test files but none assert that dangerous overrides are rejected.
- General guidance on Docker socket exposure is consistent with this: mounting
docker.sockinto a container/daemon grants the equivalent of root on the host, so the operations reachable through that daemon on behalf of lower-privileged users need their own allowlist — the socket access itself is not the only control point.
3. Multi-node clustering keeps a single SQLite file as the system of record; only proxy routing has been offloaded (medium severity). [Resolved — documented in §4.4]
The codebase already contains real multi-node plumbing: internal/docker/pool.go's ClientPool dials remote Docker daemons per node_id (with TLS config support), and internal/proxy/valkey_sync.go implements a Valkey/Dragonfly-backed (Redis RESP protocol) pub/sub + KV layer so proxy route tables stay in sync across nodes without going through SQLite. However, the actual system-of-record data — users, roles, servers, tasks, node registration (see the 20260307_001_multinode_default_node migration in internal/db/migrations.go, which backfills node_id on servers/modules) — still lives in one SQLite file on the controller node (DESIGN.md §6). Remote nodes are Docker API endpoints only; there is no replica or shard of the control-plane database. That means:
- The controller node's SQLite file is a single point of failure for the entire cluster's control plane, not just one node — losing it or its disk takes down management of every node, even though the Minecraft proxy layer (via Valkey) could in principle keep routing traffic.
- SQLite's single-writer model caps how many concurrent RPC writes (server CRUD, task scheduling, RBAC changes) the controller can absorb as node/server count grows; this is a real scaling ceiling once the cluster is large enough that control-plane writes (not proxy traffic) become the bottleneck.
- DESIGN.md documents almost none of this: the only clustering mentions in the whole document are a UI "cluster indicator" label (§3) and one line in the proto file listing (
node.proto, §5). The multi-node architecture that already exists in code (ClientPool,valkey_sync.go,node_idcolumns) has no corresponding architecture section. - This is consistent with general guidance on SQLite at scale: SQLite remains an excellent choice for single-writer, embedded workloads, but common signals for outgrowing it are multiple processes needing concurrent writes and a need for HA/failover — both of which a multi-node controller implies once more than one control-plane instance is expected to be able to accept writes. Tools like
rqlite/dqlite(Raft-replicated SQLite) orLitestream(streaming backup/PITR to object storage) are natural fits if the goal is HA and durability for the existing single-writer model without a rewrite to a client/server RDBMS; a full move to PostgreSQL is the more conventional path if genuine multi-writer/horizontal write scaling is needed.
4. CI validates a small fraction of the backend, with no Go linter (medium severity). [Resolved]
As corrected in §8 above, ci.yml only runs tests for internal/packwiz, internal/scheduler, and a filtered subset of internal/rpc/handlers. Thirteen of the twenty-one internal/ packages have zero test files at all (alias, auth, cache, command, config, events, indexers, metrics, rbac, rcon, rpc, webhook, ws), and none of the packages that do have tests (docker, proxy, db, minecraft, module, snapshot) are exercised in CI. Given finding #1 above, internal/rbac — the package enforcing every authorization decision in the system — has neither test coverage nor a CI gate. There is also no go vet/golangci-lint step; make lint only covers proto and frontend.
5. Frontend has no automated test coverage (medium severity). [Resolved — baseline]
web/carbon-panel/package.json has no Vitest, Jest, Playwright, or @testing-library dependency, and ci.yml's frontend job only runs type-checking (bun run check) and a production build (bun run build) — neither of which exercises component behavior or catches regressions in RBAC-gated UI logic, form validation, or the WebSocket-driven realtime views.
6. CD can push a new main image independently of CI's result (low severity). [Resolved]
cd.yml triggers on the same push to main that ci.yml does, but the two workflows are not chained — cd.yml has no needs/workflow_run dependency on ci.yml. A backend change that fails even the narrow test scope in finding #4 can still result in a new :latest image being built and pushed to Docker Hub from the same commit.
Status as of the 2026-09 resolution pass: recommendations 1–4 and the CD half of 6 are complete; the frontend-component-test half of 6 and the controller-HA decision in 5 remain open (see §4.4).
- Make RBAC fail closed, and add a CI gate that keeps it that way. Change
authInterceptorso that a procedure absent from all three maps is rejected (connect.CodePermissionDenied) rather than passed through — "deny by default, allow what you recognize." Then add a table-driven test ininternal/rbacthat walks every procedure registered in the generated Connect service handlers (reflection over the service descriptors, or a small codegen step) and asserts each one appears in exactly one ofPublicProcedures,AuthenticatedOnlyProcedures, orProcedurePermissions. Wire that test intoci.ymlso a forgotten mapping entry fails the build instead of shipping. This is the single highest-leverage fix in this review: it closes a live authorization gap and makes the same class of bug structurally hard to reintroduce. - Constrain
DockerOverridesto a safe subset before it reaches the Docker Engine API. Introduce an explicit allowlist (or denylist of genuinely dangerous values) forCapAdd,SecurityOpt, andVolumes.SourceinApplyOverrides, and require a separate, more privileged RBAC action (e.g. a distinctserver_config.privileged_updatescoped only to superadmins) for anything outside the safe subset. At minimum, rejectCapAddentries outside a small known-safe set (e.g.SYS_NICE,NET_BIND_SERVICE), rejectapparmor:unconfined/seccomp:unconfined, and reject bind-mount sources outside the server's own data directory. Add tests asserting dangerous overrides are rejected —internal/docker/hardening_test.goalready exercisesApplyOverridesand is the natural home for this coverage. - Expand CI to cover the packages RBAC and container-isolation correctness depend on. At minimum add
./internal/rbac/...,./internal/docker/...,./internal/auth/..., and./internal/proxy/...toci.yml(all butauthandrbacalready have test files ready to run) — a one-line change with immediate signal, plus incentive to backfillauth/rbactests given finding #1. Addgo vet ./...and agolangci-lint runstep; both are low-effort, high-signal additions to a Go CI pipeline that currently has neither. - Pin one Go version and reference it everywhere. Set
go.mod,ci.yml,release.yml, and the dev-environment docs/.air.tomlreference to the same version (ideally via a single source of truth, e.g.go.mod's directive consumed byactions/setup-go@v5'sgo-version-file: go.modinput in every workflow, so there is only one place to bump). - Document the multi-node architecture that already exists, and decide deliberately whether the controller's SQLite needs HA. Add a real "Multi-Node Clustering" section to DESIGN.md describing the current model (single controller with SQLite system-of-record + remote
ClientPoolDocker connections + Valkey-synced proxy routing) so the gap between "what's documented" and "what's built" (found ininternal/proxy/valkey_sync.go,internal/docker/pool.go, and thenode_idmigration) closes. Separately, make an explicit call on controller HA: if multi-controller failover is a real near-term goal, evaluaterqlite/dqlite(Raft-replicated SQLite, minimal application changes) before a heavier move to PostgreSQL; if it isn't,Litestream-style continuous backup to object storage is a much cheaper way to bound data loss from the existing single-writer setup. - Chain CD to CI's result and add minimal frontend test coverage. Add a
workflow_run/needsdependency (or fold both jobs into one workflow) socd.ymlcannot publish an image from a commit that failedci.yml. Separately, introduce Vitest +@testing-library/sveltefor at least the RBAC-gated UI components and form validation, since the frontend currently ships with zero automated coverage of user-facing behavior.
- Connect-RPC interceptor authorization patterns and the "ungated, not denied" failure mode: connectrpc-authz-go, rbacconnect, Connect Go interceptors docs.
- Docker socket exposure and blast radius of daemon access: OWASP Docker Security Cheat Sheet, Docker container security vulnerabilities & fixes, Docker socket exposure Q&A.
- SQLite at scale, replication, and HA options: rqlite FAQ, Litestream vs rqlite vs dqlite comparison, SQLite for production: when and how.