Installation
MCSM ships a turnkey Docker Compose stack that runs the app, the Infrarust proxy and a restricted Docker socket proxy — that's the recommended way to deploy it. You can also run it from source for development.
Prerequisites
- A host with Docker installed.
- A domain for the dashboard (e.g.
mcsm.example.com) and a domain (or wildcard) for your Minecraft servers (e.g.*.mc.example.com), both pointing at the host. - For running from source: Node.js 22+ and pnpm.
Deploy with Docker Compose
The repo's docker-compose.yml
runs three services (deploying on Coolify? Use
docker-compose.coolify.yml
instead — see Deploy with Coolify):
| Service | Purpose |
|---|---|
mcsm | The dashboard and API (port 3000). |
infrarust | The Minecraft proxy — listens on 25565 and routes each domain to its server container. |
docker-socket-proxy | A restricted proxy in front of the Docker socket, so neither MCSM nor Infrarust ever touches the raw socket. |
Clone the repository
git clone https://github.com/Niki2k1/mcsm.git
cd mcsm
Start the stack
docker compose up -d
The dashboard is now on http://localhost:3000 and Minecraft traffic is
accepted on port 25565.
docker-compose.yml sets
NUXT_SESSION_COOKIE_SECURE: "false" — otherwise browsers would silently
refuse the Secure login cookie when the dashboard is opened over plain HTTP
from a non-localhost address (LAN IP, Tailscale). Set it back to "true" if
you put a TLS-terminating reverse proxy in front.Create the admin account
On first launch MCSM shows a setup wizard that creates the admin account. There is no open registration — additional users are created later from the Admin panel.
Add a domain
Open Admin → Domains and add at least one domain (e.g. mc.example.com).
The create wizard needs it: the chosen subdomain.domain becomes the address
players connect to.
Deploy with Coolify
MCSM publishes a multi-arch image to GHCR on every push to main
(ghcr.io/niki2k1/mcsm), and the compose file is Coolify-compatible:
Add the resource
In Coolify, create a New Resource → Docker Compose, point it at the
MCSM repository and set the Docker Compose Location to
docker-compose.coolify.yml (or paste that file).
Assign the dashboard domain
Assign a domain to the mcsm service on port 3000. Coolify fills the
SERVICE_FQDN_MCSM_3000 magic variable and routes HTTPS to it.
Point your Minecraft DNS at the host
Point the DNS for your Minecraft domain — for example a wildcard
*.mc.example.com — at the host. Infrarust listens on 25565.
Deploy and set up
Deploy, run the first-launch setup wizard, then add at least one domain in the Admin panel.
Deploy on Unraid
MCSM ships Community Applications templates in the repo's
unraid/ folder. Unraid
runs one container per template, so the stack is split in two: mcsm (the
dashboard) and infrarust (the proxy). Both mount the Docker socket
directly instead of going through docker-socket-proxy.
Until the repository is listed in Community Applications, add it manually:
Apps → Settings → Template repositories, paste
https://github.com/Niki2k1/mcsm and save. The two templates then show up
under Apps.
Create the shared network
Run this once from the Unraid terminal:
docker network create infrarust
Then enable Settings → Docker → Preserve user defined networks, otherwise Unraid drops the network the next time the Docker service restarts.
Install mcsm
Install the mcsm template. Set Session password to any string of 32+
characters (openssl rand -base64 32) and change the RCON password. Leave
the network on infrarust.
Server data root (NUXT_DOCKER_DATA_ROOT) defaults to
/mnt/user/appdata/mcsm-data. Worlds are stored in servers/<name> and
backups in backups/ below it. Don't clear it: without it, worlds live in
Docker named volumes inside the Docker vDisk (20 GB by default), which a few
modpack worlds fill up, stopping every container on the box.
Install infrarust (optional)
To route several servers by domain on a single port 25565, copy
unraid/infrarust/config.toml
to /mnt/user/appdata/infrarust/config.toml, then install the infrarust
template. Point a DNS wildcard (e.g. *.mc.example.com) at your Unraid box
and forward port 25565.
The template runs Infrarust as root (--user 0). The image's default user
can't open the Docker socket or write its plugins/ folder, and the gid of
Unraid's docker group isn't the same on every release.
Without Infrarust, publish a host port per server in the create wizard and
connect with unraid-ip:port.
Turn on autostart
In the Docker tab, switch Autostart on for mcsm and
infrarust. Unraid stops its containers with docker stop when Docker or
the server shuts down. After that, --restart unless-stopped no longer
brings them back, so without autostart both stay down after a reboot.
Set up
Open the WebUI, run the first-launch wizard and add a domain under Admin → Domains.
NUXT_SESSION_COOKIE_SECURE at false because the
WebUI is reached over plain HTTP. Set it to true if you put a
TLS-terminating reverse proxy (SWAG, Nginx Proxy Manager, Traefik) in front.Run from source
For development or custom setups:
git clone https://github.com/Niki2k1/mcsm.git
cd mcsm
pnpm install
cp .env.example .env # adjust as needed
Development (hot reload):
pnpm dev
Production build and start:
pnpm build
pnpm start
infrarust) that both Infrarust and the Minecraft containers
join. The Docker Compose stack wires all of this up for you.Configure environment variables
Configuration is supplied through Nuxt runtimeConfig, so overrides must use
NUXT_-prefixed environment variables:
| Variable | Required | Description |
|---|---|---|
NUXT_SESSION_PASSWORD | ✅ | Encrypts login session cookies (min. 32 chars, e.g. openssl rand -base64 32). Without it in production, every restart logs everyone out. |
NUXT_DOCKER_HOSTS_DEFAULT_SOCKET_PATH | ✅ | Path to the Docker socket (or socket proxy) MCSM provisions on. Default /var/run/docker.sock. |
NUXT_DOCKER_NETWORK | ✅ | Shared Docker network Infrarust and the Minecraft containers join. Default infrarust. |
NUXT_DOCKER_IMAGE | – | Server image. Default itzg/minecraft-server. |
NUXT_DOCKER_DATA_ROOT | – | Absolute path on the Docker host where worlds (servers/<name>) and backups (backups/) are stored as plain directories. Empty (default) = Docker named volumes. Changing it doesn't move existing worlds or backups: servers keep running from where their world lives, but backups made under the old setting no longer show up for download or restore. |
NUXT_RCON_PASSWORD | – | RCON password set on every server for the console. Default minecraft. Change it. |
NUXT_RCON_PORT | – | RCON port inside the container. Default 25575 (never published). |
NUXT_INTERNAL_URL | – | URL where Minecraft containers reach MCSM on the shared Docker network (used for icon downloads). Default http://mcsm:3000. |
NUXT_SESSION_MAX_AGE | – | Login session lifetime in seconds. Default 1 week. |
NUXT_SESSION_COOKIE_SECURE | – | Set to false when serving MCSM over plain HTTP (no TLS proxy) — browsers refuse Secure cookies over HTTP except on localhost, so logins silently fail. Default true. |
NUXT_DOCKER_HOSTS_DEFAULT_HOST | – | Remote Docker daemon host. When set, takes precedence over the socket path. |
NUXT_OAUTH_MICROSOFT_CLIENT_ID / ..._CLIENT_SECRET / ..._TENANT | – | Enables "Sign in with Microsoft". The login button only shows when configured. |
Secure the Docker socket
In production, do not mount the bare socket into MCSM. Put a restricted
proxy such as
tecnativa/docker-socket-proxy
in front of it, allow only the endpoints MCSM needs (containers, images,
networks, volumes), and point MCSM at the proxy. The bundled
docker-compose.yml already does this — neither MCSM nor Infrarust touches
the raw socket.
Next steps
- Create your first server — see Servers & dashboard.
- Set up BlueMap or world backups.