Everything not listed in this document should behave the same as upstream Minecraft Server. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable — see the Documentation section of
instructions.mdfor links.
A Minecraft Java Edition server, packaged from itzg's server image. This package manages server.properties itself, drives the server over RCON for the things a config file cannot express, and puts a web admin console in front of it.
- Upstream repo: https://github.com/itzg/docker-minecraft-server
- Wrapper repo: https://github.com/Start9-Community/minecraft-startos
- Image and Container Runtime
- Volume and Data Layout
- File Models
- Dependencies
- Network Access and Interfaces
- Installation and First-Run Flow
- Actions
- Tasks
- Health Checks
- Backups and Restore
- Limitations and Differences
- Quick Reference for AI Consumers
Three images, and the Java the server runs on is decided at start.
| Property | Value |
|---|---|
| Images | One itzg/minecraft-server tag, an rcon-web-admin build, nginx |
| Architectures | x86_64, aarch64 |
| Command | Each image's own entrypoint |
| Subcontainer | Purpose |
|---|---|
minecraft-server-sub |
The game server — the one to attach to |
rcon-sub |
The web admin console, speaking RCON to the server |
rcon-proxy-sub |
nginx, unifying the console's two ports into one |
The server image bundles one Java — the one vanilla needs — and every other Java is downloaded on demand. Vanilla always runs on the bundled Java 25. A modded server or modpack runs on the Java chosen in the Mod Loader action (Java 25, 21, 17, or 8); any choice other than the bundled one is fetched from Adoptium by the ensure-jre oneshot into start9/jre/<version>/ on the volume the first time it is needed, then put ahead of the image's own Java on the server process's PATH. JAVA_HOME is left pointing at the image's Java, which is what the image's own tooling (mc-image-helper) runs on; only the server, and the loader installers it spawns, see the chosen one. A selected loader, version, and modpack must support the chosen Java. Switching the Java restarts the server onto it.
The oneshot verifies the tarball's SHA-256 against the Adoptium API, keeps a runtime that is already in place, removes the emSign roots from that runtime's cacerts on every run, and retries with backoff if the download fails — a modded server whose Java cannot be fetched stays waiting on it rather than starting on the wrong one.
The server image is built through the root Dockerfile, a temporary layer that upgrades Ubuntu's ca-certificates and removes the emSign roots from the bundled Java's cacerts; it comes out once upstream ships an image built on fixed stores. The server image and the itzg/rcon image the console's code is taken from are pinned by digest, so a rebuild produces the same bits rather than following a moving tag. The downloaded runtimes are not pinned: each is the latest GA build of its release line at download time.
The console image is built here, not consumed as-is. It copies rcon-web-admin 0.14.1, with its installed dependencies and core widgets, out of the itzg/rcon image and runs it on node:24.22.1-bookworm-slim. It also applies two patches to rcon-web-admin's browser code — a history.pushState call that throws and takes the page down with it, and a dropdown that renders empty until it is refreshed. The build fails loudly if either patch no longer applies, rather than silently shipping an unpatched console.
nginx exists because the console listens on two ports — HTTP on one, its websocket on another — and a browser reaching it through StartOS gets one address. The proxy serves the page, forwards the websocket, and rewrites the console's own endpoint discovery so the browser is told to connect back through the same address.
One volume, holding the server's entire data directory.
| Volume | Mount Point | Purpose |
|---|---|---|
main |
/data |
Worlds, configuration, mods, and the console's database |
| Path | Written by | Holds |
|---|---|---|
<world-name>/ |
Minecraft | One directory per world, each with level.dat |
server.properties |
Both | The server configuration |
start9/store.json |
Actions | Memory, credentials, mod loader, Java, mods, and modpack configuration |
start9/modpack.mrpack |
Actions | An uploaded modpack, read by the image on start |
start9/jre/<version>/ |
ensure-jre |
A downloaded Java runtime, kept for reuse |
rcon-db/ |
The console | Its own settings and widgets |
mods/ |
The image | Mods downloaded for a modded server, or installed from a pack |
modpack.mrpack |
The image | Its cache of a modpack fetched by URL; removed on Force Re-sync |
Worlds are discovered from the filesystem, not from a list. Any directory on the volume containing a level.dat is a world, which is what lets the world actions enumerate them and read each one's game mode, difficulty, and last-played time straight out of its NBT data.
The console's database is a subpath of the same volume mounted into its own container, so it is captured by the same backup as everything else.
Two models, read two different ways — and the difference is deliberate.
| File | Format | Modelled | Written by |
|---|---|---|---|
server.properties |
INI | Yes — FileHelper.ini |
Actions, and Minecraft itself |
start9/store.json |
JSON | Yes — FileHelper.json |
Actions only |
The store is read reactively; server.properties is not. Minecraft truncates and rewrites its properties file on every load, and during that window the file parses as empty — which would look like a changed value and restart the service in a loop. So the properties are read once at start, and the actions that change only that file call for a restart themselves.
Three properties are pinned rather than merely defaulted: RCON being enabled, the RCON port, and the server port. They are z.literal(...).catch(...), so an edited value is repaired on read — the package's control plane and its health check both depend on them.
The RCON password is generated once at install and lives in the same file. It is the credential the console and every RCON-driven action authenticate with; it is never shown to the user and never needs to be.
server.properties also holds everything the Configure Server action edits — game mode, difficulty, distances, PvP, whitelist enforcement, MOTD — with each field validated and range-checked on read, so a hand-edited nonsense value falls back to its default rather than failing the start.
The store holds what is not a Minecraft setting: the memory profile, the console's credentials, and the mod loader — with its Java, its Minecraft version, an optional loader build and its mod list, or, for a modpack, the pack's source and options.
None.
A modded server reaches out to Modrinth at start to download its files, and to Adoptium for its Java the first time a version other than the bundled one is chosen. Hosted modpacks fetch the pack itself, while uploaded packs can still fetch downloads listed in modrinth.index.json. A modded first boot therefore needs internet; vanilla needs none once installed.
Two interfaces, of very different kinds.
| Interface | Id | Type | Port | Description |
|---|---|---|---|---|
| RCON Web Admin | web-admin |
ui | 8080 | The console, through nginx |
| Minecraft | minecraft-server |
p2p | 25565 | What game clients connect to |
The game port is bound raw — no TLS, no proxy, and the external port is requested to match the internal one, because a Minecraft client dials the standard port unless the player types otherwise.
RCON is never exported. The port exists inside the service's network namespace, where the console and the package's own code reach it over loopback; nothing binds it to an address.
Authentication is rcon-web-admin's own login form, not a gate added by StartOS — and since the console holds the RCON password, reaching it is full operator control of the server. The address deliberately carries no admin@ prefix: folding the username into the URL is what the SDK would do by default, and Chromium-based browsers strip or refuse userinfo in a top-level navigation, which would break the launch link. The username is always admin, typed into the form.
Install seeds both files with defaults, generates the RCON password, and raises a critical task to set the console password.
The service cannot start until that password is set, which is what keeps the console from ever coming up with an empty credential in front of an RCON socket.
The first start then generates the world. Ordering is explicit: ensure-jre runs first when a Java has to be downloaded, the server comes up after it, the console waits for the server, and nginx waits for the console. A modded first start is much slower — it installs the loader and downloads every mod before the port opens — so it carries a far longer grace period than vanilla.
Installing this package accepts Mojang's EULA on your behalf; the server will not run otherwise.
Ten actions, in three groups.
The gameplay settings and the memory allocation.
- What it changes: most of
server.properties, plus the memory profile in the store. - Cost: the service restarts.
- Repeat safety: idempotent, pre-filled from the current state. Memory offers three named profiles plus a custom pair, and a maximum below the minimum is rejected rather than saved.
Vanilla, NeoForge, or Fabric with the Minecraft version, an optional loader build, the Java, and the mod list for the modded options — or a Modrinth modpack, which brings its own Minecraft version, loader build, mods, configs and overrides, and takes the Java it should run on.
- What it changes: the loader, the version, the loader build, the Java, and the mods in the store — and through them the Java the server runs on. For a modpack: the pack's source (a slug, a project or version URL, a direct
.mrpackURL, or an uploaded file), the Java, whether to force a re-sync, and files to exclude. - Java Version is offered for every modded option, never for vanilla. Java 21 is the default and runs NeoForge and current Fabric; Java 17 covers the 1.17–1.20 loaders; Java 8 covers packs built for it, such as Forge 1.12.2; Java 25 is the bundled one. The first start on a Java other than the bundled one downloads it.
- The loader build floats unless pinned. With NeoForge Version or Fabric Loader Version empty, the image installs the newest loader build for the Minecraft version and re-resolves it on every start, so a restart after an upstream release moves the server onto the new build. A pinned build is passed as
NEOFORGE_VERSIONorFABRIC_LOADER_VERSIONand is installed until it is changed; a build that does not exist for the Minecraft version fails the start, which the server log names. NeoForge refuses a client on a different build than the server; Fabric does not check. - Cost: the service restarts, downloading a Java it has not used before, and, for a modded start, re-downloads mods; a modpack start installs the pack.
- Repeat safety: idempotent, pre-filled. Mods are Modrinth project slugs, each optionally pinned to a version or a release channel; required dependencies are pulled automatically. An uploaded pack re-opens on the upload variant with the file empty, meaning "keep it", so the options can be changed without uploading again.
- An uploaded pack is stored on the volume at
start9/modpack.mrpack. The action enforces a 512 MiB limit and validates the rootmodrinth.index.jsonbefore replacing it. A validation or staging failure preserves the previous upload, and a SHA-256 identity instore.jsonrestarts the service only when the uploaded bytes change. - Modrinth project sources are checked on start; direct
.mrpackURLs are cached. Force Re-sync removes that URL cache and asks the image to reprocess a project source. It remains stored until turned off, and changing Exclude Files for an unchanged hosted source turns it on automatically. Changing a hosted source invalidates the old URL cache once without enabling Force Re-sync. - Switching modes removes only installer-tracked files under
mods/. This prevents jars from the prior mode loading alongside the new selection while preserving manually added mods, worlds, and configuration. Each installer retains its own manifest so returning to that mode restores its files normally. VERSIONis not set for a modpack. The image'sLATESTdefault leaves project resolution unfiltered by game version, while the pack index selects Minecraft and its loader.- Exclude Files matches paths of the pack's listed files only; it does not filter the pack's
overrides/. The package always excludesserver.propertiesandstart9/from both indexed files and override trees; other pack configuration applies normally. - Carries a warning, and it is not decorative. Existing worlds may not load across a loader or version change. Hand-picked installs require matching loader and Minecraft versions plus the client-required mods; modpack players install the matching client pack.
Generates the console password and shows it once.
- What it changes: the password in the store.
- Cost: the service restarts.
- Repeat safety: each run generates a new password. It is never user-chosen. Once a password exists, the action asks for confirmation before replacing it.
Views and edits the player whitelist, and turns enforcement on or off.
- Requires the service to be running, because it works over RCON.
- What it changes: the live whitelist, through the server itself — added and removed by name, so the server computes the right UUID for each. The enforcement flags are then written to
server.propertiesso they survive a restart. - Repeat safety: it reconciles rather than appends; the list you submit becomes the list.
Reads every world directory on the volume and reports its game mode, difficulty, hardcore and cheats flags, last-played time, and the Minecraft version that wrote it.
Sets the active world name and an optional seed, then restarts. The world itself is generated by Minecraft on the next start, not by this action — which is why an existing name is refused rather than reused.
Switches the active world to another directory on the volume and restarts. Nothing is deleted or moved.
Permanently deletes a world directory.
- Only when the service is stopped, and only for a world that is not the configured one — switch first.
- No world is preselected, and it requires typing
DELETEto confirm. - Irreversible. There is no trash; the backup is the only recovery.
Reports the configured settings and the console username. Requires the service to be running.
Queries the running server over RCON for who is online and the in-game time. Individual queries that fail are reported as unavailable rather than failing the whole action.
One, raised at install.
| Task | Severity | Raised when | Cleared when |
|---|---|---|---|
| Set Web Admin Password | critical |
Install | The action runs |
critical blocks the service from starting and suspends the ordinary controls, so a fresh install shows the task and nothing else.
Three checks, one per daemon.
| Check | Displayed as | Method | Grace |
|---|---|---|---|
minecraft-server |
"Minecraft Server" | Game port listening, then RCON port | 30s; 300s modded; 900s modpack |
rcon-admin |
"RCON Web Admin" | The console's port is listening | — |
rcon-proxy |
"RCON Web Admin Proxy" | The proxy's port is listening | — |
The server's check is two-stage on purpose. The game port opens before RCON does, and everything this package does administratively goes over RCON — so the check reports "waiting for RCON" in the window where players could connect but the console and the world actions could not.
The modded grace period is ten times the vanilla one because a modded first start downloads a loader and a mod set before it listens at all. A modpack's is longer again: a first install also downloads and verifies every jar in the pack, and a large pack over a home connection outruns the modded allowance.
The ensure-jre oneshot has no check of its own. While a Java is downloading, "Minecraft Server" reports waiting; if the download fails, it stays there and the script's error is in the service logs. The oneshot retries on its own, so restoring internet is enough.
None of the three says anything about the world: lag, a corrupt chunk, or a mod failing to load all show three green checks and an error in the server logs.
The main volume is copied wholesale — sdk.Backups.ofVolumes('main') — which is every world, the configuration, the mods, and the console's database.
A running server is flushed first. The pre-backup step connects over RCON and issues a save, so what gets copied is a consistent world rather than one mid-write. If the server is running and that flush cannot be performed, the backup fails rather than quietly capturing a torn save.
A stopped server is backed up directly, with no flush needed.
A restored instance comes back with the same worlds, console and RCON passwords, mod list, and modpack configuration. A modded server processes that stored configuration on the next start.
- Java Edition only. Bedrock clients cannot connect.
- The vanilla version is the package's, not the user's — only the modded loaders take a version.
- Changing loader, version, loader build, or Java can strand a world. Clients need the matching loader and Minecraft version plus the client-required mods or client pack; a NeoForge client also needs the server's NeoForge build.
- Installing accepts the Mojang EULA on your behalf.
- The console has one account. There is no per-user access to the admin interface, and it holds full RCON control.
- Deleting a world requires stopping the service, and cannot target the active world.
- Individual mods come from Modrinth only, by project slug. A whole pack can be uploaded as a
.mrpack, which is the way to bring in a mod from anywhere else. - Backups of a running server depend on RCON; a failed flush aborts the backup by design.
server.propertiesis managed by the package. The image's own environment-variable generation is disabled, so settings not exposed by an action must be edited in the file.- A downloaded Java is the latest build of its line at download time, and is kept until the volume is deleted; there is no action to refresh or remove one.
package_id: minecraft
image: itzg/minecraft-server # one digest-pinned tag, bundling Java 25; other Javas are downloaded on demand
architectures:
- x86_64
- aarch64
oneshots:
- ensure-jre # modded only, when store.javaVersion is not the bundled one; downloads it to start9/jre/<version>/
subcontainers:
- minecraft-server-sub # PATH leads with the downloaded Java when one is chosen
- rcon-sub # rcon-web-admin from a digest-pinned itzg/rcon, on node:24.22.1-bookworm-slim, plus two frontend patches
- rcon-proxy-sub # nginx; unifies the console's http + websocket ports and rewrites /wsconfig
volumes:
main: /data # worlds, server.properties, start9/store.json, uploaded modpack, start9/jre/, rcon-db/
file_models:
- server.properties # ini; read .once() because Minecraft rewrites it on every load
- start9/store.json # json; read .const() — memory, console credentials, mod loader + Java + mods, or the modpack's source and options
startos_managed_env_vars:
- EULA
- TYPE
- VERSION
- INIT_MEMORY
- MAX_MEMORY
- RCON_PASSWORD
- SKIP_SERVER_PROPERTIES
- PATH # modded only, when a downloaded Java is chosen; JAVA_HOME stays the image's
- MODRINTH_PROJECTS # modded only
- MODRINTH_DOWNLOAD_DEPENDENCIES # modded only
- MODRINTH_MODPACK # modpack only; VERSION is then not set
- MODRINTH_FORCE_SYNCHRONIZE # modpack only, when Force Re-sync is on
- MODRINTH_EXCLUDE_FILES # modpack only; package protections plus user exclusions
- MODRINTH_OVERRIDES_EXCLUSIONS # modpack only; protects server.properties and start9/**
dependencies: [] # modded starts need internet (Modrinth, and Adoptium for a Java not yet downloaded); uploaded packs can list remote downloads
interfaces:
web-admin: { type: ui, port: 8080 } # nginx in front of the console; console's own login
minecraft-server: { type: p2p, port: 25565 } # raw TCP, external port preserved
actions:
- configure-server
- mod-loader
- set-web-admin-password
- manage-whitelist # only-running; drives RCON then persists the flags
- list-worlds
- create-world
- select-world
- delete-world # only-stopped; requires typing DELETE
- get-server-info # only-running
- get-live-server-stats # only-running
tasks:
- { action: set-web-admin-password, severity: critical } # install only
health_checks:
- minecraft-server # game then RCON; 30s vanilla / 300s NeoForge or Fabric / 900s modpack
- rcon-admin
- rcon-proxy