README
¶
A self-hosted control plane for Minecraft server networks.
Status: pre-alpha. Shardkeep is being built in the open. Nothing here is ready for production yet.
Shardkeep manages a pool of Docker nodes and lets you provision, run, migrate, back up and monitor every server in your network (lobby, survival, minigames and the Velocity proxy in front of them) from one web UI and a public API.
Why Shardkeep
- Nodes dial out. Each node connects to the Controller over mutual TLS. No open ports, no exposed Docker API, works behind NAT.
- The Controller is not a single point of failure. If it goes down, servers keep running, schedules and backups keep firing, and nodes reconcile when it returns.
- Network operations built in. Migrate servers between nodes, restore a backup as a new server, clone selectively.
- A curated catalog. Server software, plugins and mods with compatibility checks, cached locally for offline installs.
- Team-scoped permissions and an immutable audit log.
Get started
On a Linux machine with Docker:
curl -fsSL https://shardkeep.gg/install.sh | sh
Read the script first if you prefer, or follow the installation guide to do the same by hand.
Our promise
Shardkeep is free software under the AGPL-3.0. We will never hold back self-hosting features for a hosted service. If a hosted offering ever exists, it will only add hosting, billing, managed operations and support.
Project layout
| Path | Contents |
|---|---|
apps/controller |
The Controller: web UI backend, public API, scheduling, certificate authority |
apps/agent |
The Agent: runs on every node, executes workloads through Docker |
proto/ |
gRPC contracts between the Controller and Agents |
web/ |
Angular web UI |
docs/ |
The design document (the documentation itself is at docs.shardkeep.gg, from shardkeep/docs) |
brand/ |
Logos, colours, design tokens and brand guide |
deploy/ |
Docker Compose and container images |
Community
- Chat: Discord
- Questions and ideas: open an issue using the Question or Idea template; vote on ideas with 👍
- Security issues: see SECURITY.md. Please do not open public issues for vulnerabilities.
- Support the project: Liberapay
Contributing
Contributions are welcome. Read CONTRIBUTING.md first: we use Conventional Commits and the Developer Certificate of Origin. Everyone is expected to follow the Code of Conduct.
Trademark
The code is free to fork; the Shardkeep name and logo are not. See TRADEMARKS.md.
Minecraft is a trademark of Mojang AB. Shardkeep is not affiliated with or endorsed by Mojang or Microsoft.
Directories
¶
| Path | Synopsis |
|---|---|
|
apps
|
|
|
agent
command
Command shardkeep-agent runs on every Node.
|
Command shardkeep-agent runs on every Node. |
|
agent/internal/artifacts
Package artifacts keeps the Agent's cache of software artifacts, fetched from the Controller over mTLS.
|
Package artifacts keeps the Agent's cache of software artifacts, fetched from the Controller over mTLS. |
|
agent/internal/backup
Package backup takes, stores, exports and restores server data.
|
Package backup takes, stores, exports and restores server data. |
|
agent/internal/docker
Package docker is a small Docker Engine API client built on the standard library.
|
Package docker is a small Docker Engine API client built on the standard library. |
|
agent/internal/files
Package files is the Agent's file manager for server data.
|
Package files is the Agent's file manager for server data. |
|
agent/internal/hostinfo
Package hostinfo reads what the Agent reports about its Node: capacity (CPU, memory, disk), current usage and pressure conditions.
|
Package hostinfo reads what the Agent reports about its Node: capacity (CPU, memory, disk), current usage and pressure conditions. |
|
agent/internal/identity
Package identity keeps the Agent's identity: its private key, its Node certificate and the Controller CA it trusts.
|
Package identity keeps the Agent's identity: its private key, its Node certificate and the Controller CA it trusts. |
|
agent/internal/localstate
Package localstate keeps what the Agent must remember across restarts and Controller outages: the last desired specs it received, the events it recorded but the Controller has not acknowledged, and whether the Node was revoked.
|
Package localstate keeps what the Agent must remember across restarts and Controller outages: the last desired specs it received, the events it recorded but the Controller has not acknowledged, and whether the Node was revoked. |
|
agent/internal/netconfig
Package netconfig writes what Shardkeep manages in servers' files for the network: the proxy's whole Velocity configuration, and on members the settings that make them accept only players the proxy forwards.
|
Package netconfig writes what Shardkeep manages in servers' files for the network: the proxy's whole Velocity configuration, and on members the settings that make them accept only players the proxy forwards. |
|
agent/internal/operations
Package operations carries out the Controller's requests about one server: console commands, the live console, and the file manager.
|
Package operations carries out the Controller's requests about one server: console commands, the live console, and the file manager. |
|
agent/internal/reconcile
Package reconcile converges each server on the Node to its desired spec: it validates the spec, creates, starts, stops or deletes the server's container, watches it with the status ping, applies the restart policy, and reports observed state and events.
|
Package reconcile converges each server on the Node to its desired spec: it validates the spec, creates, starts, stops or deletes the server's container, watches it with the status ping, applies the restart policy, and reports observed state and events. |
|
agent/internal/runtime
Package runtime runs servers as Docker containers: one hardened container and one named volume per server.
|
Package runtime runs servers as Docker containers: one hardened container and one named volume per server. |
|
agent/internal/schedule
Package schedule runs servers' schedules on the Agent, from the specs it stores, so they keep running while the Controller is down.
|
Package schedule runs servers' schedules on the Agent, from the specs it stores, so they keep running while the Controller is down. |
|
agent/internal/session
Package session holds the Agent's long-lived mTLS session with the Controller: Hello, Welcome, heartbeats and the exchange of server state and events, reconnecting with backoff when the connection drops.
|
Package session holds the Agent's long-lived mTLS session with the Controller: Hello, Welcome, heartbeats and the exchange of server state and events, reconnecting with backoff when the connection drops. |
|
agent/internal/slp
Package slp implements the Minecraft Server List Ping, which the Agent uses to decide a server is RUNNING: the server answers a status request on its game port.
|
Package slp implements the Minecraft Server List Ping, which the Agent uses to decide a server is RUNNING: the server answers a status request on its game port. |
|
agent/internal/templates
Package templates maps the template names in server specs to what the Agent actually runs.
|
Package templates maps the template names in server specs to what the Agent actually runs. |
|
controller
command
Command shardkeep runs the Shardkeep Controller: the control plane that owns desired state, serves the web UI and public API, and manages Agents.
|
Command shardkeep runs the Shardkeep Controller: the control plane that owns desired state, serves the web UI and public API, and manages Agents. |
|
controller/internal/admin
Package admin implements the Controller's command-line administration: creating the first administrator on a fresh install and recovering an account whose owner is locked out.
|
Package admin implements the Controller's command-line administration: creating the first administrator on a fresh install and recovering an account whose owner is locked out. |
|
controller/internal/agentsvc
Package agentsvc serves the Controller side of the Agent protocol: enrollment on its own listener, and (from the session milestone) the mTLS session every enrolled Agent holds open.
|
Package agentsvc serves the Controller side of the Agent protocol: enrollment on its own listener, and (from the session milestone) the mTLS session every enrolled Agent holds open. |
|
controller/internal/api
Package api serves the Controller's public REST API, /api/v1.
|
Package api serves the Controller's public REST API, /api/v1. |
|
controller/internal/api/apigen
Package apigen provides primitives to interact with the openapi HTTP API.
|
Package apigen provides primitives to interact with the openapi HTTP API. |
|
controller/internal/artifacts
Package artifacts keeps the Controller's cache of software artifacts (server jars): files in the data directory named by their SHA-256, with a database record of what each one is.
|
Package artifacts keeps the Controller's cache of software artifacts (server jars): files in the data directory named by their SHA-256, with a database record of what each one is. |
|
controller/internal/auth
Package auth holds the credential building blocks: Argon2id password hashing, random tokens stored only as hashes, and login rate limiting.
|
Package auth holds the credential building blocks: Argon2id password hashing, random tokens stored only as hashes, and login rate limiting. |
|
controller/internal/ca
Package ca is the Controller's certificate authority.
|
Package ca is the Controller's certificate authority. |
|
controller/internal/catalog
Package catalog answers the Controller's software questions from the stored catalog snapshot (synced and verified by catalogsync): which versions of a template exist, and which build, download URL and published checksum a version resolves to.
|
Package catalog answers the Controller's software questions from the stored catalog snapshot (synced and verified by catalogsync): which versions of a template exist, and which build, download URL and published checksum a version resolves to. |
|
controller/internal/catalogsync
Package catalogsync keeps the Controller's copy of the central catalog: it fetches the signed snapshot index, verifies it against the trusted keys, refuses anything not newer than what it has, checks every object's hash and size, and stores the snapshot in one transaction.
|
Package catalogsync keeps the Controller's copy of the central catalog: it fetches the signed snapshot index, verifies it against the trusted keys, refuses anything not newer than what it has, checks every object's hash and size, and stores the snapshot in one transaction. |
|
controller/internal/domain
Package domain holds the Controller's core types and the rules of the state machines in docs/design.md.
|
Package domain holds the Controller's core types and the rules of the state machines in docs/design.md. |
|
controller/internal/localnode
Package localnode enrolls the Agent bundled with a Controller (the Compose install's) without anyone copying a token: the Controller creates that Node and keeps a fresh enrollment token in a file only the bundled Agent shares, until the Node is enrolled.
|
Package localnode enrolls the Agent bundled with a Controller (the Compose install's) without anyone copying a token: the Controller creates that Node and keeps a fresh enrollment token in a file only the bundled Agent shares, until the Node is enrolled. |
|
controller/internal/provision
Package provision runs the PROVISIONING workflow's asynchronous part: placement and reservation happen when a server is created; this worker resolves the server's software to an exact build, makes sure the artifact is in the Controller's cache, records it on the server and pushes the spec to the Node.
|
Package provision runs the PROVISIONING workflow's asynchronous part: placement and reservation happen when a server is created; this worker resolves the server's software to an exact build, makes sure the artifact is in the Controller's cache, records it on the server and pushes the spec to the Node. |
|
controller/internal/store
Package store persists the Controller's state in PostgreSQL: desired state, observed state and history.
|
Package store persists the Controller's state in PostgreSQL: desired state, observed state and history. |
|
controller/internal/store/storetest
Package storetest runs integration tests against a real PostgreSQL.
|
Package storetest runs integration tests against a real PostgreSQL. |
|
controller/internal/tlsserve
Package tlsserve provides the TLS configuration for the Controller's web UI and API.
|
Package tlsserve provides the TLS configuration for the Controller's web UI and API. |
|
controller/internal/transfers
Package transfers runs the workflows that move data into a server: restoring a backup in place or as a new server, migrating a server to another Node, and cloning parts of one server into another.
|
Package transfers runs the workflows that move data into a server: restoring a backup in place or as a new server, migrating a server to another Node, and cloning parts of one server into another. |
|
controller/internal/webui
Package webui serves the web UI (web/, built into build/app) embedded in the Controller binary: static files with long-lived caching for hashed names, index.html for the app's own routes, and a strict Content Security Policy with a fresh nonce for every page load.
|
Package webui serves the web UI (web/, built into build/app) embedded in the Controller binary: static files with long-lived caching for hashed names, index.html for the app's own routes, and a strict Content Security Policy with a fresh nonce for every page load. |
|
internal
|
|
|
cron
Package cron parses five-field cron expressions and finds when they next match.
|
Package cron parses five-field cron expressions and finds when they next match. |
|
enrollment
Package enrollment holds what the Controller and the Agent share about Node enrollment: the token format, and the Agent's side of the exchange.
|
Package enrollment holds what the Controller and the Agent share about Node enrollment: the token format, and the Agent's side of the exchange. |
|
pluginjar
Package pluginjar reads what a Bukkit or Paper plugin jar says about itself: the name and version in its paper-plugin.yml or plugin.yml.
|
Package pluginjar reads what a Bukkit or Paper plugin jar says about itself: the name and version in its paper-plugin.yml or plugin.yml. |
|
properties
Package properties reads and edits Minecraft's server.properties, a Java properties file, keeping every comment and the order of the lines.
|
Package properties reads and edits Minecraft's server.properties, a Java properties file, keeping every comment and the order of the lines. |
|
version
Package version holds build information injected at release time.
|
Package version holds build information injected at release time. |
Click to show internal directories.
Click to hide internal directories.