Minecraft Discord Bot

A Go-based Discord bot for managing Minecraft servers. It uses the Docker API to create, manage, and delete servers via Discord commands.

Uses the itzg/minecraft-server Docker image.

Features

• Slash Commands: Uses Discord / slash commands.
• Dynamic Provisioning: Creates new Minecraft containers on demand.
• Multiple Modpacks: Supports Spigot, Paper, Vanilla, Fabric, Forge, etc.
• Persistent Storage: Bind-mounts server data to the host.
• Port Allocation: Automatically assigns available ports from a defined pool.
• Server Ownership: Only the creator (or a Discord Admin) can delete servers or send RCON commands.
• Quotas: Limits how many servers a user can have.
• Auto-Pausing: Suspends containers when no players are online to save RAM.

Prerequisites

• Go 1.21+
• Docker
• A Discord Bot Token (with the applications.commands scope enabled).

Environment Variables

Create a .env file in the same directory as the binary with the following configuration:

# Required
DISCORD_TOKEN=your_discord_bot_token

# Optional - Security
ALLOWED_CHANNEL_ID=123456789012345678    # Only allow commands in this specific channel ID
MAX_SERVERS_PER_USER=3                   # Limit the number of servers a single user can own

# Optional - Network & Paths
SERVER_DOMAIN=minecraft.example.com      # The domain to display to users when a server is created
PORT_POOL=30000-30020                    # The range of host ports available for new servers
MINECRAFT_DATA_DIR=/opt/minecraft/servers # Where host volume data will be saved

# Optional - Default Server Overrides (Fallback if not provided in the slash command)
DEFAULT_SERVER_TYPE=VANILLA
DEFAULT_SERVER_VERSION=LATEST
DEFAULT_SERVER_MODE=survival
DEFAULT_SERVER_HEAP=2G
TZ=Europe/Copenhagen

Setup & Installation

The recommended way to run this bot is via docker compose, as it inherently manages the bot's background process and auto-restarts on system reboots.

1. Clone the repository
2. Configure Environment Variables:

   cp .env.example .env
   nano .env # Add your Discord token

3. Start the Bot Container:

   docker compose up -d

4. View Logs:

   docker logs -f minecraft-bot

(Note: The docker-compose.yml automatically mounts /var/run/docker.sock so the bot can spawn sibling containers for the Minecraft servers).

Security Notice: Running Docker as root is common, but for maximum isolation, it is highly recommended to run this bot using Docker Rootless Mode under a dedicated user account.

Please read the Rootless Docker Setup Guide for step-by-step instructions.

Discord Commands

All commands are nestled under the /mc root command.

/mc list

Lists all Minecraft servers managed by the bot, including stopped containers, showing their name, state, status, and connection address when a port is assigned.

/mc create

Spins up a brand new Minecraft server.

• name (Required): The name of the server (e.g. smp-season-1)
• type (Optional): The modpack type (VANILLA, PAPER, SPIGOT, etc.). Defaults to VANILLA.
• version (Optional): The Minecraft version (1.21.1, LATEST, etc.). Defaults to LATEST.
• mode (Optional): Game mode (survival, creative). Defaults to survival.
• heap (Optional): Max Java heap size (2G, 4G, 500M). Defaults to 2G. Max is 10G.

/mc logs

Fetches the last 50 lines of logs from the specified server.

• name (Required): The name of the server.

/mc rcon

[Creator or Admin Only] Executes a server command via RCON.

• name (Required): The name of the server.
• command (Required): The command string (e.g. say Hello world, op Steve).

/mc difficulty

[Creator or Admin Only] Sets the server difficulty to peaceful, easy, normal, or hard. If the server is running, the change is applied immediately and persisted in server.properties; if stopped, it is persisted for the next start.

• name (Required): The name of the server.
• value (Required): The difficulty.

/mc start | stop | restart

Standard lifecycle controls for bot-managed Minecraft containers. /mc restart will start a stopped server instead of failing.

/mc remove

[Creator or Admin Only] Immediately stops and deletes the Docker container. (Note: If you want to permanently delete the world data, you must add purge:true to the command).

Security Considerations

• RCON Injection: It is safe to expose /mc rcon to users. The arguments are passed to Docker via an explicit command array (bypassing the shell /bin/sh -c), making it immune to bash injection.
• Permissions: Ensure the system user running this bot has chmod access to the host folder defined in MINECRAFT_DATA_DIR so Docker can write the initial server.properties and EULA files correctly.