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:
| 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
# uncomment the mcsm `ports:` block in docker-compose.yml to expose the UI
docker compose up -d
The dashboard is now on http://localhost:3000 and Minecraft traffic is
accepted on port 25565.
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 and point it at the
MCSM repository (or paste docker-compose.yml).
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.
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_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_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.