How to Self-Host a Minecraft Server with Docker

Why Self-Host a Minecraft Server?

Running your own Minecraft server gives you full control over world settings, mods, player access, and performance — without paying a monthly hosting fee. The itzg/minecraft-server Docker image handles Java version management, automatic updates, and mod loading, making it the simplest way to run a dedicated server.

Self-hosting is especially worthwhile if you already have a home server or VPS. A vanilla Minecraft server for 5-10 players runs comfortably on modest hardware.

Official project: itzg/docker-minecraft-server on GitHub

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended) with Docker and Docker Compose installed
• 4 GB of RAM minimum (8 GB recommended for modded servers)
• 2+ CPU cores
• 10 GB of free disk space (more for large worlds)
• Port 25565 open on your firewall or router (port forwarding guide)

Docker Compose Configuration

Create a directory for your server and a docker-compose.yml file:

mkdir -p ~/minecraft && cd ~/minecraft

services:
  minecraft:
    image: itzg/minecraft-server:2025.3.0
    container_name: minecraft-server
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: "VANILLA"
      VERSION: "LATEST"
      MEMORY: "4G"
      MAX_PLAYERS: "20"
      VIEW_DISTANCE: "12"
      MOTD: "My Self-Hosted Minecraft Server"
      ENABLE_RCON: "true"
      RCON_PASSWORD: "change-this-strong-password"
      DIFFICULTY: "normal"
      MODE: "survival"
      SPAWN_PROTECTION: "0"
      ENABLE_COMMAND_BLOCK: "true"
      REPLACE_ENV_VARIABLES: "TRUE"
    volumes:
      - minecraft_data:/data
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 5G
    stdin_open: true
    tty: true

volumes:
  minecraft_data:

Environment variable notes:

Variable	Purpose
EULA	Required. Accepts the Mojang/Microsoft EULA. Must be TRUE.
TYPE	Server type: VANILLA, PAPER, FABRIC, FORGE, SPIGOT, etc.
VERSION	Minecraft version. LATEST auto-downloads the newest release. Pin to e.g. 1.21.4 for stability.
MEMORY	JVM heap allocation. 4G for vanilla, 6-8G for modded.
RCON_PASSWORD	Remote console password. Change this from the default.
REPLACE_ENV_VARIABLES	Enables environment variable substitution in config files.

Start the server:

docker compose up -d

First startup takes 2-5 minutes while the server downloads the Minecraft JAR and generates the world. Monitor progress with:

docker compose logs -f minecraft

Wait for Done! For help, type "help" before connecting.

Connecting to Your Server

From Minecraft Java Edition:

1. Click Multiplayer → Add Server
2. Enter your server’s IP address (or localhost if playing on the same machine)
3. Port is 25565 by default — no need to specify it unless you changed it

For remote access from outside your network, set up port forwarding for TCP port 25565, or use Tailscale for a private connection without exposing ports.

Running a Paper Server (Recommended)

Paper is a high-performance fork of Spigot with better tick rates and plugin support. Most server operators prefer it over vanilla:

services:
  minecraft:
    image: itzg/minecraft-server:2025.3.0
    container_name: minecraft-paper
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: "PAPER"
      VERSION: "LATEST"
      MEMORY: "4G"
      ENABLE_RCON: "true"
      RCON_PASSWORD: "change-this-strong-password"
      SPIGET_RESOURCES: ""
      PAPERBUILD: "LATEST"
    volumes:
      - paper_data:/data
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 5G

volumes:
  paper_data:

Paper supports Bukkit and Spigot plugins. Drop .jar plugin files into the plugins/ directory inside your data volume.

Installing Mods (Fabric/Forge)

For a Fabric modded server:

environment:
  EULA: "TRUE"
  TYPE: "FABRIC"
  VERSION: "1.21.4"
  MEMORY: "6G"

For Forge:

environment:
  EULA: "TRUE"
  TYPE: "FORGE"
  VERSION: "1.21.4"
  MEMORY: "8G"

Place mod .jar files in the mods/ directory inside your data volume:

docker compose exec minecraft ls /data/mods/

To add mods, copy them into the volume:

docker cp my-mod.jar minecraft-server:/data/mods/
docker compose restart minecraft

Tip: Modded servers need more RAM. Allocate 6-8 GB for small mod packs, 10-12 GB for large ones like ATM or Create.

Backups

The data volume contains everything: world files, configuration, plugins, and player data. Back it up regularly.

Manual backup:

docker compose exec minecraft rcon-cli save-all
docker compose pause minecraft
tar -czf minecraft-backup-$(date +%Y%m%d).tar.gz -C /var/lib/docker/volumes/minecraft_minecraft_data/_data .
docker compose unpause minecraft

For automated backups, add the itzg/mc-backup sidecar container:

services:
  backups:
    image: itzg/mc-backup:2026.2.1
    container_name: minecraft-backup
    environment:
      RCON_HOST: minecraft
      RCON_PASSWORD: "change-this-strong-password"
      BACKUP_INTERVAL: "6h"
      INITIAL_DELAY: "5m"
      PRUNE_BACKUPS_DAYS: "7"
    volumes:
      - minecraft_data:/data:ro
      - ./backups:/backups
    depends_on:
      - minecraft
    restart: unless-stopped

This creates compressed backups every 6 hours and removes backups older than 7 days. For more options, see our backup strategy guide.

Allowlisting and Administration

Allowlist (Whitelist)

Set ENFORCE_WHITELIST: "TRUE" and WHITELIST with a comma-separated list of player names:

environment:
  ENFORCE_WHITELIST: "TRUE"
  WHITELIST: "player1,player2,player3"

Or manage the whitelist through RCON:

docker compose exec minecraft rcon-cli whitelist add PlayerName

Operator Access

Grant operator (admin) access:

environment:
  OPS: "your_username"

Or via RCON:

docker compose exec minecraft rcon-cli op PlayerName

RCON Console

Access the server console remotely:

docker compose exec minecraft rcon-cli

This lets you run any server command: /ban, /tp, /give, /gamemode, etc.

Performance Tuning

Setting	Vanilla	Modded
MEMORY	3-4 GB	6-12 GB
VIEW_DISTANCE	10-12	6-8
SIMULATION_DISTANCE	8-10	4-6
MAX_PLAYERS	20	10-15

For Paper servers, add Aikar’s recommended JVM flags:

environment:
  JVM_OPTS: "-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1"

Troubleshooting

Server Won’t Start

Symptom: Container starts but no players can connect.

Fix: Check logs for errors:

docker compose logs minecraft | tail -50

Common causes:

• EULA not set to TRUE
• Port 25565 already in use (docker compose down any conflicting containers)
• Insufficient RAM (increase MEMORY and the container memory limit)

High Tick Lag (TPS Below 20)

Symptom: Block breaking delays, entity rubber-banding.

Fix:

• Switch from Vanilla to Paper (TYPE: "PAPER")
• Lower VIEW_DISTANCE to 8
• Lower SIMULATION_DISTANCE to 6
• Remove or optimize resource-heavy mods
• Check entity counts: docker compose exec minecraft rcon-cli debug start

Players Cannot Connect from Outside

Symptom: Connection times out from remote networks.

Fix:

• Verify port 25565 is forwarded (TCP) on your router
• Check your firewall: sudo ufw allow 25565/tcp
• Confirm your public IP matches what players are using
• Consider Tailscale or a Cloudflare Tunnel for easier access

Resource Requirements

Configuration	RAM	CPU	Disk
Vanilla, 1-5 players	2-3 GB	2 cores	5 GB
Vanilla, 10-20 players	4-6 GB	2-4 cores	10 GB
Paper, 20+ players	6-8 GB	4 cores	15 GB
Modded (small pack)	6-8 GB	4 cores	20 GB
Modded (large pack)	10-12 GB	4+ cores	30+ GB

Minecraft server performance depends heavily on single-thread clock speed. A 4-core CPU at 4.0 GHz outperforms an 8-core at 2.5 GHz for Minecraft.

Verdict

The itzg/minecraft-server Docker image makes running a Minecraft server trivially easy. Paper type is the best choice for most servers — better performance than vanilla, full plugin support, and active development. Only use vanilla if you specifically need parity with the official server.

For managing multiple game servers, consider Pterodactyl or Crafty Controller — both provide web UIs for managing Minecraft and other game servers.

Related

• Best Self-Hosted Game Servers
• Pterodactyl vs Crafty Controller
• Docker Compose Basics
• Port Forwarding Guide
• Tailscale Setup
• Backup Strategy
• Best Hardware for Game Servers