Minecraft Server on Proxmox

Run a Minecraft server on your Proxmox host in minutes. Supports Java and Bedrock on both Virtual Machines (VM) and Containers (LXC/CT).

Table of Contents

• Features
• Quickstart
  • Proxmox Provisioning
  • VM (DHCP)
  • VM (Static IP)
  • LXC/CT
  • Bedrock
• Backups
• Auto-Update
• Configuration
• Admin/Commands
• Troubleshooting
• Contributing
• References

🧩 Features

• VM/CT provisioning with clear steps for Proxmox
• Java and Bedrock installers
• Auto-update for Java via update.sh
• Backups with systemd timers or cron
• Sensible defaults: EULA, screen, memory flags
• Optional systemd service for auto-start

Tip

Default ports: Java 25565/TCP, Bedrock 19132/UDP. Open these on your firewall/router.

🏗️ Architecture Overview

High-level layout: Proxmox → VM/CT → Minecraft (Java/Bedrock) with backup/update hooks.

🚀 Quickstart

Requirements: Proxmox host, Ubuntu 24.04 LTS (recommended) or Debian 11/12 guest.

VM (DHCP)

1. Create a VM (2–4 vCPU, 4–8 GB RAM, 20+ GB disk).
2. SSH into the VM and run:

wget https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_minecraft.sh
chmod +x setup_minecraft.sh
./setup_minecraft.sh

Access console:

screen -r minecraft

Tip

On Debian 11/12, the installer falls back to OpenJDK 17 if Java 21 isn’t available.

VM (Static IP)

If you prefer static networking (Ubuntu netplan example):

sudo tee /etc/netplan/01-mc.yaml >/dev/null <<'YAML'
network:
  version: 2
  ethernets:
    ens18:
      addresses: [192.168.1.50/24]
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: [1.1.1.1,8.8.8.8]
YAML
sudo netplan apply

Then install as in DHCP.

Warning

Use the correct interface name (e.g., ens18, eth0) and network details for your environment.

LXC/CT

Create a container (Ubuntu 24.04 template recommended). Enable Nesting if needed. Inside the container:

wget https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_minecraft_lxc.sh
chmod +x setup_minecraft_lxc.sh
./setup_minecraft_lxc.sh

Access console:

screen -r minecraft

Bedrock

VM or LXC/CT:

wget https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_bedrock.sh
chmod +x setup_bedrock.sh
./setup_bedrock.sh

Access console:

screen -r bedrock

🧰 Proxmox Provisioning

Run these from a Proxmox node shell as root.

VM (Cloud-Init Ubuntu)

DHCP example:

wget https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/proxmox_vm_provision.sh
chmod +x proxmox_vm_provision.sh
./proxmox_vm_provision.sh \
  --vmid 19265 \
  --name mc-vm \
  --cores 4 \
  --memory 8192 \
  --disk 32 \
  --bridge vmbr0 \
  --storage local-lvm \
  --ssh-key /root/.ssh/id_rsa.pub \
  --post-install "https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_minecraft.sh"

Static IP example:

./proxmox_vm_provision.sh \
  --vmid 19266 \
  --name mc-vm-static \
  --cores 4 \
  --memory 8192 \
  --disk 32 \
  --bridge vmbr0 \
  --storage local-lvm \
  --ssh-key /root/.ssh/id_rsa.pub \
  --ip 192.168.1.50/24 \
  --gw 192.168.1.1 \
  --dns 1.1.1.1 \
  --post-install "https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_minecraft.sh"

Notes:

• The script auto-downloads an Ubuntu cloud image (default noble).
• It creates a reusable template if missing, then clones the VM.
• --post-install injects a cloud-init snippet to install and start Minecraft.
• Use --snippets-store if your snippets storage is not local.

Container (LXC Ubuntu)

wget https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/proxmox_ct_provision.sh
chmod +x proxmox_ct_provision.sh
./proxmox_ct_provision.sh \
  --ctid 12650 \
  --hostname mc-ct \
  --cores 4 \
  --memory 8192 \
  --disk 16 \
  --bridge vmbr0 \
  --storage local-lvm \
  --post-install "https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_minecraft_lxc.sh"

Notes:

• Pulls the Ubuntu 24.04 standard template if missing.
• Creates an unprivileged container with nesting=1,keyctl=1 and DHCP.
• If --post-install is set, it installs dependencies and sets up Minecraft inside the CT.

🗃️ Backups

Back up worlds and server files before updates. Choose systemd or cron.

Option A: systemd (Java/Bedrock)

Configuration file (used by the service):

sudo tee /etc/mc_backup.conf >/dev/null <<'EOF'
# Directories
MC_SRC_DIR=/opt/minecraft
MC_BEDROCK_DIR=/opt/minecraft-bedrock
BACKUP_DIR=/var/backups/minecraft
# Retention (days) for optional cleanup logic (manual step)
RETAIN_DAYS=7
EOF

Backup service and timer:

sudo tee /etc/systemd/system/mc-backup.service >/dev/null <<'EOF'
[Unit]
Description=Minecraft backup (tar)

[Service]
Type=oneshot
EnvironmentFile=/etc/mc_backup.conf
ExecStart=/bin/mkdir -p "${BACKUP_DIR}"
ExecStart=/bin/bash -c 'tar -czf "${BACKUP_DIR}/java-$(date +%%F).tar.gz" "${MC_SRC_DIR}"'
ExecStart=/bin/bash -c '[ -d "${MC_BEDROCK_DIR}" ] && tar -czf "${BACKUP_DIR}/bedrock-$(date +%%F).tar.gz" "${MC_BEDROCK_DIR}" || true'
EOF

sudo tee /etc/systemd/system/mc-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Nightly Minecraft backup

[Timer]
OnCalendar=*-*-* 03:30:00
Persistent=true

[Install]
WantedBy=timers.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now mc-backup.timer

Run on demand:

sudo systemctl start mc-backup.service

Option B: cron

Nightly backups (note escaped % in cron):

crontab -e
30 3 * * * tar -czf /var/backups/minecraft/mc-$(date +\%F).tar.gz /opt/minecraft

Bedrock example:

crontab -e
45 3 * * * tar -czf /var/backups/minecraft/bedrock-$(date +\%F).tar.gz /opt/minecraft-bedrock

♻️ Auto-Update

Java edition ships with /opt/minecraft/update.sh:

cd /opt/minecraft
./update.sh

Weekly cron:

crontab -e
0 4 * * 0 /opt/minecraft/update.sh >> /var/log/minecraft-update.log 2>&1

Note

Bedrock requires a manual download from Mojang. See bedrock_helper.sh for a reminder message.

⚙️ Configuration

/etc/mc_backup.conf

• MC_SRC_DIR: Java server path (default /opt/minecraft)
• MC_BEDROCK_DIR: Bedrock server path (default /opt/minecraft-bedrock)
• BACKUP_DIR: Backup target directory (default /var/backups/minecraft)
• RETAIN_DAYS: Days to keep backups (manual cleanup policy)

JVM memory (Java)

Edit /opt/minecraft/start.sh:

#!/bin/bash
java -Xms2G -Xmx4G -jar server.jar nogui

Small: -Xms1G -Xmx2G, Medium: -Xms2G -Xmx4G.

Firewall

sudo ufw allow 25565/tcp    # Java
sudo ufw allow 19132/udp    # Bedrock
sudo ufw enable

Optional: systemd service (Java)

Use minecraft.service:

sudo cp minecraft.service /etc/systemd/system/minecraft.service
sudo systemctl daemon-reload
sudo systemctl enable --now minecraft

🕹️ Admin/Commands

See SERVER_COMMANDS.md for operator setup, screen usage, and common commands.

🔧 Troubleshooting

• Java 21 unavailable on Debian 11 → falls back to OpenJDK 17.
• Missing start.sh → recreate as shown and chmod +x start.sh.
• Permission issues → ensure ownership of /opt/minecraft* or use sudo.

🤝 Contributing

• Open an issue
• Submit a Pull Request

📚 References

• PaperMC: https://papermc.io/
• Mojang Bedrock Downloads: https://www.minecraft.net/en-us/download/server/bedrock
• Proxmox Docs: https://pve.proxmox.com/wiki/Main_Page