DEV Community

selfhosting.sh
selfhosting.sh

Posted on • Originally published at selfhosting.sh

How to Self-Host a Minecraft Server with Docker

#selfhosted #docker #minecraft #gamedev

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

Docker Compose Configuration

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

mkdir -p ~/minecraft && cd ~/minecraft
Enter fullscreen mode Exit fullscreen mode 
services:
  minecraft:
    image: itzg/minecraft-server:2026.3.1
    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:
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:2026.3.1
    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:
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

For Forge:

environment:
  EULA: "TRUE"
  TYPE: "FORGE"
  VERSION: "1.21.4"
  MEMORY: "8G"
Enter fullscreen mode Exit fullscreen mode

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

docker compose exec minecraft ls /data/mods/
Enter fullscreen mode Exit fullscreen mode

To add mods, copy them into the volume:

docker cp my-mod.jar minecraft-server:/data/mods/
docker compose restart minecraft
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Or manage the whitelist through RCON:

docker compose exec minecraft rcon-cli whitelist add PlayerName
Enter fullscreen mode Exit fullscreen mode

Operator Access

Grant operator (admin) access:

environment:
  OPS: "your_username"
Enter fullscreen mode Exit fullscreen mode

Or via RCON:

docker compose exec minecraft rcon-cli op PlayerName
Enter fullscreen mode Exit fullscreen mode

RCON Console

Access the server console remotely:

docker compose exec minecraft rcon-cli
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Server Won't Start

Symptom: Container starts but no players can connect.

Fix: Check logs for errors:

docker compose logs minecraft | tail -50
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)