---
title: Installation
description: Deploy MCSM with Docker Compose, Coolify, Unraid or from source
navigation:
  icon: i-lucide-download
---

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`](https://github.com/Niki2k1/mcsm/blob/main/docker-compose.yml)
runs three services (deploying on Coolify? Use
[`docker-compose.coolify.yml`](https://github.com/Niki2k1/mcsm/blob/main/docker-compose.coolify.yml)
instead — see [Deploy with Coolify](#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. |

::steps

### Clone the repository

```bash [Terminal]
git clone https://github.com/Niki2k1/mcsm.git
cd mcsm
```

### Start the stack

```bash [Terminal]
docker compose up -d
```

The dashboard is now on `http://localhost:3000` and Minecraft traffic is
accepted on port `25565`.

::note
This setup has no HTTPS proxy, so `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:

::steps

### 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/`](https://github.com/Niki2k1/mcsm/tree/main/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**.

::steps

### Create the shared network

Run this once from the Unraid terminal:

```bash [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`](https://github.com/Niki2k1/mcsm/blob/main/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**.

::

::note
The templates leave `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:

```bash [Terminal]
git clone https://github.com/Niki2k1/mcsm.git
cd mcsm
pnpm install
cp .env.example .env   # adjust as needed
```

**Development** (hot reload):

```bash [Terminal]
pnpm dev
```

**Production build and start:**

```bash [Terminal]
pnpm build
pnpm start
```

::note
When running from source you also need Infrarust running against the same
Docker daemon with its docker provider enabled, and a shared Docker network
(default name `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

::warning
MCSM provisions servers by talking to the Docker Engine API — and a web app
with raw socket access is effectively **root on the host**.
::

In production, do **not** mount the bare socket into MCSM. Put a restricted
proxy such as
[`tecnativa/docker-socket-proxy`](https://github.com/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](/features/servers).
- Set up [BlueMap](/features/bluemap) or [world backups](/features/backups).