How I Built a Modded Minecraft Server on a Debian VPS Using Docker (Step-by-Step Guide)

In this guide, I will explain how I set up a fully working modded Minecraft server on a Debian VPS using Docker. The goal of this project was not only to host a server but also to understand Linux server management, Docker containers, and game server architecture.

This setup allows friends to join my Minecraft world over the internet, and it also supports mods for enhanced gameplay.

1. Setting Up the VPS

I started with a Debian-based VPS. After logging in via SSH, I updated the system:

Then I installed essential tools:

These tools help with file editing, monitoring system performance, and managing network security.

• curl → Used to download data or files from the internet
• wget → Downloads files directly from URLs
• git → Helps to clone and manage code from GitHub
• nano → A simple text editor for editing files in terminal
• ufw → A firewall tool used to secure the server by controlling network access
• htop → A system monitor to check CPU, RAM, and running processes

2. Installing Docker

Instead of manually installing Minecraft server dependencies, I used Docker for containerization:

Docker allows me to run Minecraft in an isolated environment without affecting the main system.

3. Creating Server Directory

I organized my Minecraft server files in a clean structure inside my Linux user account (jigri) to keep everything easy to manage and avoid confusion.

What this means

• /home/jigri/ → This is my Linux user directory (jigri is my system user)
• server/minecraft/ → This is the main folder where my Minecraft server will run
• mkdir -p → Creates folders step by step, even if parent folders don’t exist

What each folder is for

• data/ → Stores Minecraft world files, configs, and server data
• backups/ → Keeps saved copies of the world in case of crashes or mistakes
• scripts/ → Stores automation scripts like backups or restart commands

4. Configuring Minecraft Server with Docker

I used the popular Docker image from itzg: To run my Minecraft server, I used a prebuilt Docker image from itzg, which is one of the most popular Minecraft server images for Docker. Instead of manually installing Java, server files, and dependencies, Docker handles everything inside a container.

I created a docker-compose.yml file inside my server directory:

MODDED MINECRAFT CONFIG (FORGE)

Paste this:

services:
minecraft:
image: itzg/minecraft-server

container_name: minecraft

ports:
— “25565:25565”

environment:
EULA: “TRUE”

TYPE: “FORGE”
VERSION: “1.20.1”

MEMORY: “6G”

volumes:
— ./data:/data

Get Pratyush Khadka’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

restart: unless-stopped

5. started the server

After creating the file, I started the Minecraft server using Docker Compose:

When I run this command: Sudo docker compose up -d

• Docker checks the docker-compose.yml file
• It downloads the itzg Minecraft server image from Docker Hub if not already available
• It creates a container with all required dependencies (Java, server files, Forge setup)
• It starts the Minecraft server in the background

6. Making the Server Public

To allow My friends to join the Minecraft server, I needed to open the required network port. Minecraft uses port 25565, so I allowed traffic through the firewall.

Opening the Minecraft Port

I ran the following command ufw allow 25565 Then I enabled the firewall:

• ufw (Uncomplicated Firewall) controls incoming and outgoing network traffic on the server
• allow 25565 opens the Minecraft port so external players can connect
• Without this step, the server would only work locally inside the VPS

Then my Friends join server using: SERVER_IP:25565

7. Adding Mods to the Server

All Minecraft mods are stored inside the /home/jigri/server/minecraft/data/mods directory

To install mods, I simply add the .jar mod files into this folder. There are two main ways to do this:

Method 1: Using SCP (from my local computer)

Method 2: Using wget (direct download on VPS)

I mostly used SCP (Secure Copy Protocol) because it is faster, safer, and more reliable for transferring files from my local computer to the VPS.

What SCP does

SCP is used to securely copy files between your computer and a remote server over SSH. It encrypts the transfer so the file is safely sent to the VPS without any risk.

Important Note

• I used the real server IP in actual setup (not a fake one for production)
• SCP is always run from your local machine
• The file is directly uploaded into the Minecraft mods folder on the server

After transferring the mod file, I restarted the server using docker restart minecraft so the changes take effect:

8. Enabling and Managing Whitelist

By default, Minecraft servers come with a whitelist feature. This feature allows only approved players to join the server.I used this feature to keep my server private and only allow my friends to join.Enabling Whitelist

To turn on whitelist, I used: whitelist on

All game commands are executed in the server CLI using RCON (not inside the Minecraft game).

I accessed it using: docker exec -it minecraft rcon-cli

After enabling whitelist, I manually added my friends:

Connecting with TLauncher and Player Types

Since I also had a friend using TLauncher (a non-premium Minecraft launcher), I had to adjust the server authentication mode.

I changed this setting in server.properties:

• online-mode=true → Only official Minecraft (Java Edition) accounts can join
• online-mode=false → Allows non-premium clients (like TLauncher) to join

What I Learned

This project helped me understand:

• Linux server management
• Docker containerization
• Networking and firewall configuration
• Game server hosting
• Modded Minecraft architecture

Setting up a modded Minecraft server on a VPS was not just about gaming it was a hands-on learning experience in Linux server management, Docker containerization, networking, and system security.

It helped me understand how real-world servers are structured and managed in production environments.