Minecraft Server with Docker & mcstatus

Introduction
Prerequisites
Project Structure
Quickstart
Usage and Configuration
Verify Server Status
Minimal docker-compose.yml
Stop and Cleanup
Checklist

Introduction

This repository provides a minimal Docker-based setup for running a Minecraft server using Docker Compose. It demonstrates containerization, volume persistence, and external availability checks via mcstatus — without requiring the Minecraft game client or in-depth knowledge of the game itself.

Setup

Prerequisites

A V-Server running Ubuntu/Debian
Docker

Ensure your system is up to date:

sudo apt update && sudo apt install -y docker.io docker-compose-v2 git

docker-compose-v2 installs the Compose V2 plugin, which is invoked as docker compose (with a space) — the syntax used throughout this document. The legacy docker-compose package (Compose V1, written in Python) is a different, unmaintained tool; Docker ended support for it after June 2023. If your distribution does not ship docker-compose-v2, install docker-compose-plugin from Docker's official repository instead.

Project Structure

minecraft-server/
├── docker-compose.yml
├── .gitignore
└── data/                # Automatically created when the server runs it includes all the server data including settings etcpp

Quickstart

Install dependencies:

sudo apt update && sudo apt install -y docker.io docker-compose-v2 git

Clone the repository:

git clone git@github.com:BenjaminTietz/minecraft-server.git
cd minecraft-server

Generate and configure the .env file:
The environment file will be created automatically from env.template. Adjust the values to match your setup (optional):
```
cp env_template.txt .env
nano .env (optional)
```
Start the Minecraft server:
```
docker compose up -d
```

Install mcstatus and check server status:

python -m pip install mcstatus
mcstatus localhost:25565 status

Usage and Configuration

You can configure the server using environment variables in .env.

Default environment:

EULA: "TRUE" # Required to accept Minecraft EULA
MOTD: "Welcome to my server!" # Message of the Day

Volumes

All world data and configuration are persisted in the ./data folder:

volumes:
  - ./data:/data

Ports

The default Minecraft port is exposed:

ports:
  - "25565:25565"

For cloud deployments, you may map it to another port, e.g., 8888:25565.

Written this way the port is published on all host interfaces, so on a V-Server with a public IP the server is reachable from the internet the moment it starts. That is intended for a public server and a mistake for a private one — restrict it with a firewall rule, or bind it to a single interface by prefixing the host side of the mapping ("127.0.0.1:25565:25565" for local access only). Note that the Minecraft protocol is not HTTP: a TLS-terminating reverse proxy, as used for the web projects in this section, does not apply here.

Verify Server Status (without Minecraft client)

Install mcstatus:

python -m pip install mcstatus

Check server status:

mcstatus localhost:25565 status

Example output:

version: v1.21.5 (protocol 770)
motd: "A Minecraft Server"
players: 0/20 No players online

Minimal docker-compose.yml

services:
  minecraft-server:
    image: itzg/minecraft-server # community image, not published by Mojang
    container_name: mc-server
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE" # (optional) use an .env
    volumes:
      - ./data:/data
    restart: on-failure

The image reference carries no tag, so Docker resolves it to :latest — a later docker compose pull can therefore swap the server version underneath a world that was created with the previous one. Pin an explicit tag for a reproducible setup.

Stop and Cleanup

docker compose down

To remove all persisted data:

rm -rf ./data