Complete Guide: Setting Up Minecraft Server with Pangolin

hhf.technoloy · August 11, 2025, 4:52pm

Complete Guide: Setting Up Minecraft Server with Pangolin

This guide will walk you through setting up a self-hosted Minecraft server using Crafty Controller and exposing it securely to the internet using Pangolin tunneling solution.

Prerequisites

Before starting, ensure you have:

Server/VPS: A Linux server or virtual machine (Ubuntu/Debian recommended)
Docker and Docker Compose: Installed on your server
Domain Name: A registered domain pointed to your server (e.g., from Namecheap, Cloudflare, etc.)
Open Ports: The following ports must be open on your server and firewall:
- TCP: 80, 443 (for web traffic)
- UDP: 51820, 21820 (for Pangolin tunneling)
- TCP: 25565 (for Minecraft)
Pangolin Account: Sign up at pangolin.io
Minecraft Java Edition: For testing the server

Part 1: Server Preparation

Step 1: Connect to Your Server

ssh user@your-server-ip

Step 2: Install Docker (if not already installed)

# Update package list
sudo apt update

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in for group changes to take effect
exit
ssh user@your-server-ip

Step 3: Install Docker Compose

# Download Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# Make it executable
sudo chmod +x /usr/local/bin/docker-compose

# Verify installation
docker-compose --version

Step 4: Create Project Directory

mkdir minecraft-pangolin
cd minecraft-pangolin

Part 2: Crafty Controller Setup

Step 1: Create Docker Compose File for Crafty

nano docker-compose.yml

Step 2: Add Crafty Configuration

Copy and paste this configuration:

services:
  crafty_container:
    container_name: crafty_container
    image: registry.gitlab.com/crafty-controller/crafty-4:latest
    restart: unless-stopped
    environment:
      - TZ=Etc/UTC
    ports:
      - "8443:8443"  # HTTPS Web UI
      - "8123:8123"  # HTTP Web UI
      - "19132:19132/udp"  # Bedrock
      - "25565-25600:25565-25600"  # Java
      - "8000:8000"  # Dynmap plugin
    volumes:
      - ./docker/backups:/crafty/backups
      - ./docker/logs:/crafty/logs
      - ./docker/servers:/crafty/servers
      - ./docker/config:/crafty/app/config
      - ./docker/import:/crafty/import

Step 3: Create Required Directories

mkdir -p docker/{backups,logs,servers,config,import}

Step 4: Start Crafty Container

docker compose up -d

Step 5: Get Default Credentials

# Wait a moment for the container to initialize
sleep 10

# Find the default credentials
cat docker/config/default-creds.txt

Save these credentials - you’ll need them to log in!

Step 6: Access Crafty Web UI

Open your browser and navigate to:

https://your-server-ip:8443

Note: You’ll see a security warning because of the self-signed certificate. It’s safe to proceed.

Step 7: Log In to Crafty

Use the credentials from Step 5 to log in.

Part 3: Creating the Minecraft Server

Step 1: Navigate to Servers

In the Crafty dashboard, click on “Servers” in the left menu.

Step 2: Create New Server

Click “Create New Server” button.

Step 3: Configure Server Settings

Server Type: Minecraft Java
Server Version: Select latest stable (e.g., 1.20.4)
Server Name: MC Demo (or your preferred name)
Memory:
- Minimum: 2000 MB
- Maximum: 4000 MB (adjust based on your server’s RAM)
Server Port: 25565 (default)

Click “Build Server”

Step 4: Start the Server

Click on your newly created server
Click the “Start” button
Accept the Minecraft EULA when prompted
Click OK on the port forwarding notification
Wait for the server to fully initialize (watch the console for “Done” message)

Part 4: Pangolin Installation

Step 1: Install Pangolin Base

Create a new terminal session and run:

cd ~
mkdir pangolin
cd pangolin

# Download and run the Pangolin installer
curl -fsSL https://get.pangolin.io | bash

Step 2: Configure Pangolin Installation

Follow the installer prompts:

Choose Docker as the container type
Enter your base domain (e.g., example.com)
Enter dashboard subdomain (e.g., pangolin.example.com)
Enter email for Let’s Encrypt certificates
Configure email settings (optional, can skip)
Choose to install Gerbil (recommended: yes)

Step 3: Verify Pangolin Installation

docker ps

You should see containers for:

pangolin
gerbil
traefik

Part 5: Newt Tunnel Configuration

Step 1: Access Pangolin Dashboard

Navigate to your Pangolin dashboard:

https://pangolin.your-domain.com

Step 2: Create Organization

If first time:

Click “Create Organization”
Enter organization name (e.g., “Lab”)
Click “Create”

Step 3: Create Site

Go to “Sites” tab
Click “Add Site”
Enter site name (e.g., “Minecraft-Server”)
Click “Create Site”
Copy the generated newt command

Step 4: Add Newt to Docker Compose

Go back to your minecraft-pangolin directory:

cd ~/minecraft-pangolin
nano docker-compose.yml

Add the newt service to your existing docker-compose.yml:

  newt:
    image: ghcr.io/fosrl/newt:latest
    container_name: newt
    restart: unless-stopped
    command: [
      "tunnel",
      "--remote", "https://pangolin.your-domain.com",
      "--token", "YOUR_TOKEN_HERE",
      "--site-id", "YOUR_SITE_ID_HERE"
    ]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - default

Important: Replace YOUR_TOKEN_HERE and YOUR_SITE_ID_HERE with values from the copied newt command.

Step 5: Connect to Pangolin Network

Add this to the bottom of your docker-compose.yml:

networks:
  default:
    external:
      name: pangolin

Step 6: Restart Services

docker compose down
docker compose up -d

Step 7: Verify Newt Connection

docker logs newt

You should see “Successfully connected to Pangolin endpoint” message.

Part 6: Exposing Services via Pangolin

Step 1: Expose Crafty Web UI

In the Pangolin dashboard:

Go to “Resources” tab
Click “Add Resource”
Configure HTTP resource:
- Name: crafty
- Type: HTTP Resource (toggle ON)
- Subdomain: crafty
- Site: Select your site (e.g., “Minecraft-Server”)
Click “Create Resource”

Step 2: Configure Crafty Target

In the resource settings page
Under “Target Configuration”, add target:
- Method: https
- IP/Hostname: crafty_container
- Port: 8443
Click “Save Targets”

Your Crafty UI is now accessible at: https://crafty.your-org.pangolin.io

Step 3: Expose Minecraft Server Port

Click “Add Resource” again
Configure TCP resource:
- Name: Minecraft
- Type: HTTP Resource (toggle OFF)
- Protocol: TCP
- Port Number: 25565
- Site: Select your site
Click “Create Resource”

Step 4: Update Firewall Rules

For AWS EC2:

Go to EC2 Dashboard → Security Groups
Select your instance’s security group
Add inbound rule:
- Type: Custom TCP
- Port: 25565
- Source: 0.0.0.0/0

For other providers:

# Using ufw (Ubuntu/Debian)
sudo ufw allow 25565/tcp
sudo ufw reload

# Using firewalld (CentOS/RHEL)
sudo firewall-cmd --permanent --add-port=25565/tcp
sudo firewall-cmd --reload

Step 5: Configure Traefik Entrypoints

Edit the Traefik configuration to add the Minecraft port:

cd ~/pangolin
nano config/traefik/traefik_config.yml

Add the TCP entrypoint for Minecraft (add this to the existing entryPoints section):

entryPoints:
  http:
    address: ":80"
    # ... existing config
  https:
    address: ":443"
    # ... existing config
  minecraft:  # Add this new entrypoint
    address: ":25565/tcp"

Step 6: Configure Port Mapping

Edit the main Pangolin docker-compose file:

nano docker-compose.yml

Add port mapping to the gerbil service:

  gerbil:
    ports:
      - 51820:51820/udp
      - 21820:21820/udp
      - 443:443
      - 80:80
      - 25565:25565  # Add this line

Step 7: Restart Pangolin Stack

docker compose down
docker compose up -d

Step 8: Configure Minecraft Target in Pangolin

Back in Pangolin dashboard, in your Minecraft resource settings:

Under “Target Configuration”, add target:
- IP/Hostname: crafty_container
- Port: 25565
Click “Save Targets”

Important Note: If the TCP resource creation shows you need to add entrypoints, make sure you’ve completed Step 5 (Traefik entrypoints configuration) and restarted the stack.

Part 7: Testing and Connection

Step 1: Get Your Server Address

Your Minecraft server address will be:

your-org.pangolin.io:25565

Step 2: Test with Minecraft Client

Open Minecraft Java Edition
Click “Multiplayer”
Click “Add Server”
Enter server details:
- Server Name: Pangolin Server
- Server Address: your-org.pangolin.io:25565
Click “Done”

Step 3: Connect to Server

Select your server from the list
Click “Join Server”
You should successfully connect!

Step 4: Verify in Crafty

Check the Crafty console - you should see your player joining the server.

Part 8: Advanced Configuration (Optional)

Complete Traefik Configuration Example

Here’s what a complete traefik_config.yml should look like with all entrypoints:

# config/traefik/traefik_config.yml
api:
  dashboard: true

entryPoints:
  http:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: https
          scheme: https
          permanent: true
  
  https:
    address: ":443"
    http:
      tls:
        certResolver: letsencrypt
  
  # Minecraft Java server ports
  minecraft:
    address: ":25565/tcp"
  
  # Additional server ports (if needed)
  minecraft2:
    address: ":25566/tcp"
  
  # Bedrock edition (if needed)
  bedrock:
    address: ":19132/udp"
  
  # Voice chat plugin (if needed)
  voicechat:
    address: ":24454/udp"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
  file:
    directory: "/etc/traefik/dynamic"
    watch: true
  http:
    endpoint: "http://pangolin:3001/api/v1/traefik-config"
    pollInterval: "5s"

certificatesResolvers:
  letsencrypt:
    acme:
      email: your-email@example.com
      storage: /letsencrypt/acme.json
      httpChallenge:
        entryPoint: http

Proxy Protocol Configuration

Note: Proxy Protocol is only supported by Minecraft Java Edition and requires additional configuration. Most users won’t need this unless they’re running multiple servers or need to preserve client IP addresses.

If you need to enable Proxy Protocol:

Edit Traefik configuration:

cd ~/pangolin
nano config/traefik/dynamic_config.yml

Add TCP service with Proxy Protocol:

tcp:
  routers:
    minecraft:
      rule: "HostSNI(`*`)"
      entryPoints:
        - "minecraft"
      service: "minecraft-service"
  
  services:
    minecraft-service:
      loadBalancer:
        servers:
          - address: "crafty_container:25565"
        proxyProtocol:
          version: 1

Enable Proxy Protocol in your Minecraft server:
- For Velocity proxy: Set proxy-protocol = true in velocity.toml
- For BungeeCord: Add proxy_protocol: true to config.yml
- For Paper/Spigot: Requires additional plugins

Multiple Server Ports

To expose additional Minecraft servers:

Add entrypoints in Traefik configuration:

# config/traefik/traefik_config.yml
entryPoints:
  minecraft:
    address: ":25565/tcp"
  minecraft2:
    address: ":25566/tcp"
  minecraft3:
    address: ":25567/tcp"
  # Add more as needed

Add ports to the gerbil service in docker-compose.yml:

gerbil:
  ports:
    - 25565:25565
    - 25566:25566
    - 25567:25567

In Crafty, create servers on different ports (25566, 25567, etc.)
Create separate TCP resources in Pangolin for each port
Configure targets for each resource

Voice Chat Support

For plugins like Simple Voice Chat:

Add UDP port mapping to gerbil service in docker-compose.yml:

gerbil:
  ports:
    - 24454:24454/udp

Add UDP entrypoint in Traefik configuration:

# config/traefik/traefik_config.yml
entryPoints:
  udp-24454:
    address: ":24454/udp"

In Pangolin config, enable raw resources:

# config/config.yml
flags:
  allow_raw_resources: true

Restart the stack for changes to take effect:

docker compose down
docker compose up -d

Troubleshooting

Container Won’t Start

# Check logs
docker logs crafty_container
docker logs newt

# Verify network exists
docker network ls | grep pangolin

Can’t Connect to Minecraft Server

Verify port is open:

netstat -tuln | grep 25565

Check Docker port mapping:

docker port crafty_container

Test connection locally:

telnet localhost 25565

SSL Certificate Issues

# Check Traefik logs
docker logs traefik

# Verify DNS records
nslookup your-domain.com

Player IP Shows as Proxy

This is expected behavior without Proxy Protocol. The server will see connections coming from the proxy IP. Only Minecraft Java Edition supports Proxy Protocol for preserving client IPs.

Performance Issues

Increase Docker memory limits
Optimize JVM flags in Crafty server settings
Monitor resource usage:

docker stats

Security Recommendations

Change Default Passwords: Always change Crafty’s default admin password
Firewall Rules: Only open required ports
Regular Updates: Keep Docker images updated
Backups: Enable automatic backups in Crafty
Resource Limits: Set appropriate memory/CPU limits in Docker
Access Control: Use Pangolin’s authentication features for the web UI

Conclusion

You now have a fully functional Minecraft server accessible through Pangolin’s secure tunneling system! Your server is protected behind Pangolin’s proxy, and both the game server and management interface are accessible through your custom domain.

Remember that standard TCP mode will show all players connecting from the proxy IP address. This is normal and doesn’t affect gameplay. Proxy Protocol support requires additional configuration and is only available for Java Edition servers.

Complete Guide: Setting Up Minecraft Server with Pangolin

Complete Guide: Setting Up Minecraft Server with Pangolin

Table of Contents

Prerequisites

Part 1: Server Preparation

Step 1: Connect to Your Server

Step 2: Install Docker (if not already installed)

Step 3: Install Docker Compose

Step 4: Create Project Directory

Part 2: Crafty Controller Setup

Step 1: Create Docker Compose File for Crafty

Step 2: Add Crafty Configuration

Step 3: Create Required Directories

Step 4: Start Crafty Container

Step 5: Get Default Credentials

Step 6: Access Crafty Web UI

Step 7: Log In to Crafty

Part 3: Creating the Minecraft Server

Step 1: Navigate to Servers

Step 2: Create New Server

Step 3: Configure Server Settings

Step 4: Start the Server

Part 4: Pangolin Installation

Step 1: Install Pangolin Base

Step 2: Configure Pangolin Installation

Step 3: Verify Pangolin Installation

Part 5: Newt Tunnel Configuration

Step 1: Access Pangolin Dashboard

Step 2: Create Organization

Step 3: Create Site

Step 4: Add Newt to Docker Compose

Step 5: Connect to Pangolin Network

Step 6: Restart Services

Step 7: Verify Newt Connection

Part 6: Exposing Services via Pangolin

Step 1: Expose Crafty Web UI

Step 2: Configure Crafty Target

Step 3: Expose Minecraft Server Port

Step 4: Update Firewall Rules

Step 5: Configure Traefik Entrypoints

Step 6: Configure Port Mapping

Step 7: Restart Pangolin Stack

Step 8: Configure Minecraft Target in Pangolin

Part 7: Testing and Connection

Step 1: Get Your Server Address

Step 2: Test with Minecraft Client

Step 3: Connect to Server

Step 4: Verify in Crafty

Part 8: Advanced Configuration (Optional)

Complete Traefik Configuration Example

Proxy Protocol Configuration

Multiple Server Ports

Voice Chat Support

Troubleshooting

Container Won’t Start

Can’t Connect to Minecraft Server

SSL Certificate Issues

Player IP Shows as Proxy

Performance Issues

Security Recommendations

Conclusion