homelab-docs/MINECRAFT.md

# Minecraft Servers

Minecraft servers running on docker-host2 via Crafty Controller 4.

---

## Servers Overview

| Server | Address | Port | Version | Status |
|--------|---------|------|---------|--------|
| **Hutworld** | hutworld.htsn.io | 25565 | Paper 1.21.11 | Running |
| **Backrooms** | backrooms.htsn.io | 25566 | Paper 1.21.4 | Running (LAN only*) |

*Backrooms needs port forwarding configured in UniFi

---

## Quick Reference

### Hutworld (Main Server)

| Setting | Value |
|---------|-------|
| **Web GUI** | https://mc.htsn.io |
| **Game Server (Java)** | hutworld.htsn.io:25565 |
| **Game Server (Bedrock)** | hutworld.htsn.io:19132 |
| **Host** | docker-host2 (10.10.10.207) |
| **Server Type** | Paper 1.21.11 |
| **World Name** | hutworld |
| **Memory** | 2GB min / 4GB max |

### Backrooms (Horror/Exploration)

| Setting | Value |
|---------|-------|
| **Web GUI** | https://mc.htsn.io |
| **Game Server (Java)** | backrooms.htsn.io:25566 |
| **Host** | docker-host2 (10.10.10.207) |
| **Server Type** | Paper 1.21.4 |
| **World Name** | backrooms |
| **Memory** | 512MB min / 1.5GB max |
| **Datapack** | The Backrooms v2.2.0 |

**Backrooms Features:**
- 50+ custom dimensions based on Backrooms lore
- Use `/execute in backrooms:level0 run tp @s ~ ~ ~` to travel to Level 0
- Horror-themed exploration gameplay
- No client mods required (datapack only)

---

## Crafty Controller Access

| Setting | Value |
|---------|-------|
| **URL** | https://mc.htsn.io |
| **Username** | admin |
| **Password** | See `/crafty/data/config/default-creds.txt` on docker-host2 |

**Get password:**
```bash
ssh docker-host2 'cat ~/crafty/data/config/default-creds.txt'
```

---

## Current Status

### Completed

- [x] Crafty Controller 4.4.7 deployed on docker-host2
- [x] Traefik reverse proxy configured (mc.htsn.io → 10.10.10.207:8443)
- [x] DNS A record created for hutworld.htsn.io (non-proxied, points to public IP)
- [x] Port forwarding configured via UniFi API:
  - TCP/UDP 25565 → 10.10.10.207 (Java Edition)
  - UDP 19132 → 10.10.10.207 (Bedrock via Geyser)
- [x] Server files transferred from Windows PC (D:\Minecraft\mcss\servers\hutworld)
- [x] Server imported into Crafty and running
- [x] Paper upgraded from 1.21.5 to 1.21.11
- [x] Plugins updated (GSit 3.1.1, LuckPerms 5.5.22)
- [x] Orphaned plugin data cleaned up
- [x] LuckPerms database restored with original permissions
- [x] Automated backups to TrueNAS configured (every 6 hours)

### Pending

- [ ] Change Crafty admin password to something memorable
- [ ] Test external connectivity from outside network

---

## Import Instructions

To import the hutworld server in Crafty:

1. Go to **Servers** → Click **+ Create New Server**
2. Select **Import Server** tab
3. Fill in:
   - **Server Name:** `Hutworld`
   - **Import Path:** `/crafty/import/hutworld`
   - **Server JAR:** `paper.jar`
   - **Min RAM:** `2048` (2GB)
   - **Max RAM:** `6144` (6GB)
   - **Server Port:** `25565`
4. Click **Import Server**
5. Go to server → Click **Start**

---

## Server Configuration

### World Data

| World | Description |
|-------|-------------|
| hutworld | Main overworld |
| hutworld_nether | Nether dimension |
| hutworld_the_end | End dimension |

### Installed Plugins

| Plugin | Version | Purpose |
|--------|---------|---------|
| EssentialsX | 2.20.1 | Core server commands |
| EssentialsXChat | 2.20.1 | Chat formatting |
| EssentialsXSpawn | 2.20.1 | Spawn management |
| Geyser-Spigot | Latest | Bedrock Edition support |
| floodgate | Latest | Bedrock authentication |
| GSit | 3.1.1 | Sit/lay/crawl animations |
| LuckPerms | 5.5.22 | Permissions management |
| PluginPortal | 2.2.2 | Plugin management |
| Vault | 1.7.3 | Economy/permissions API |
| ViaVersion | Latest | Multi-version support |
| ViaBackwards | Latest | Older client support |
| randomtp | Latest | Random teleportation |

**Removed plugins** (cleaned up 2026-01-03):
- GriefPrevention, Multiverse-Core, Multiverse-Portals, ProtocolLib, WorldEdit, WorldGuard (disabled/orphaned)

---

## Docker Configuration

**Location:** `~/crafty/docker-compose.yml` on docker-host2

```yaml
services:
  crafty:
    image: registry.gitlab.com/crafty-controller/crafty-4:4.4.7
    container_name: crafty
    restart: unless-stopped
    environment:
      - TZ=America/New_York
    ports:
      - "8443:8443"    # Web GUI (HTTPS)
      - "8123:8123"    # Dynmap (if used)
      - "25565:25565"  # Minecraft Java
      - "25566:25566"  # Additional server
      - "19132:19132/udp"  # Minecraft Bedrock (Geyser)
    volumes:
      - ./data/backups:/crafty/backups
      - ./data/logs:/crafty/logs
      - ./data/servers:/crafty/servers
      - ./data/config:/crafty/app/config
      - ./data/import:/crafty/import
```

---

## Traefik Configuration

**File:** `/etc/traefik/conf.d/crafty.yaml` on CT 202 (10.10.10.250)

```yaml
http:
  routers:
    crafty-secure:
      entryPoints:
        - websecure
      rule: "Host(`mc.htsn.io`)"
      service: crafty
      tls:
        certResolver: cloudflare
      priority: 50

  services:
    crafty:
      loadBalancer:
        servers:
          - url: "https://10.10.10.207:8443"
        serversTransport: crafty-transport@file

  serversTransports:
    crafty-transport:
      insecureSkipVerify: true
```

---

## Port Forwarding (UniFi)

Configured via UniFi controller on UCG-Fiber (10.10.10.1):

| Rule Name | Port | Protocol | Destination | Status |
|-----------|------|----------|-------------|--------|
| Minecraft Java | 25565 | TCP/UDP | 10.10.10.207:25565 | Active |
| Minecraft Bedrock | 19132 | UDP | 10.10.10.207:19132 | Active |
| Minecraft Backrooms | 25566 | TCP/UDP | 10.10.10.207:25566 | **PENDING** |

**To add Backrooms port forwarding:**
1. Open UniFi controller: https://10.10.10.1
2. Go to Settings → Firewall & Security → Port Forwarding
3. Add new rule:
   - Name: `Minecraft Backrooms`
   - Port: `25566`
   - Protocol: `TCP/UDP`
   - Forward to: `10.10.10.207:25566`

---

## DNS Records (Cloudflare)

| Record | Type | Value | Proxied |
|--------|------|-------|---------|
| mc.htsn.io | CNAME | htsn.io | Yes (for web GUI) |
| hutworld.htsn.io | A | 70.237.94.174 | No (direct for game traffic) |
| backrooms.htsn.io | A | 70.237.94.174 | No (direct for game traffic) |

**Note:** Game traffic (25565, 25566, 19132) cannot be proxied through Cloudflare - only HTTP/HTTPS works with Cloudflare proxy.

---

## LuckPerms Web Editor

After server is running:

1. Open Crafty console for Hutworld server
2. Run command: `/lp editor`
3. A unique URL will be generated (cloud-hosted by LuckPerms)
4. Open the URL in browser to manage permissions

The editor is hosted by LuckPerms, so no additional port forwarding is needed.

---

## Backup Configuration

### Automated Backups to TrueNAS

Backups run automatically every 6 hours and are stored on TrueNAS.

| Setting | Value |
|---------|-------|
| **Destination** | TrueNAS (10.10.10.200) |
| **Path** | `/mnt/vault/users/backups/minecraft/` |
| **Frequency** | Every 6 hours (12am, 6am, 12pm, 6pm) |
| **Retention** | 14 backups (~3.5 days of history) |
| **Size** | ~2.3 GB per backup |
| **Script** | `/home/hutson/minecraft-backup.sh` on docker-host2 |
| **Log** | `/home/hutson/minecraft-backup.log` on docker-host2 |

### Backup Script

**Location:** `~/minecraft-backup.sh` on docker-host2

```bash
#!/bin/bash
# Minecraft Server Backup Script
# Backs up Crafty server data to TrueNAS

BACKUP_SRC="$HOME/crafty/data/servers/19f604a9-f037-442d-9283-0761c73cfd60"
BACKUP_DEST="hutson@10.10.10.200:/mnt/vault/users/backups/minecraft"
DATE=$(date +%Y-%m-%d_%H%M)
BACKUP_NAME="hutworld-$DATE.tar.gz"
LOCAL_BACKUP="/tmp/$BACKUP_NAME"

# Create compressed backup (exclude large unnecessary files)
tar -czf "$LOCAL_BACKUP" \
    --exclude="*.jar" \
    --exclude="cache" \
    --exclude="libraries" \
    --exclude=".paper-remapped" \
    -C "$HOME/crafty/data/servers" \
    19f604a9-f037-442d-9283-0761c73cfd60

# Transfer to TrueNAS
sshpass -p 'GrilledCh33s3#' scp -o StrictHostKeyChecking=no "$LOCAL_BACKUP" "$BACKUP_DEST/"

# Clean up local temp file
rm -f "$LOCAL_BACKUP"

# Keep only last 14 backups on TrueNAS
sshpass -p 'GrilledCh33s3#' ssh -o StrictHostKeyChecking=no hutson@10.10.10.200 '
    cd /mnt/vault/users/backups/minecraft
    ls -t hutworld-*.tar.gz 2>/dev/null | tail -n +15 | xargs -r rm -f
'
```

### Cron Schedule

```bash
# View current schedule
ssh docker-host2 'crontab -l | grep minecraft'

# Output: 0 */6 * * * /home/hutson/minecraft-backup.sh >> /home/hutson/minecraft-backup.log 2>&1
```

### Manual Backup Commands

```bash
# Run backup manually
ssh docker-host2 '~/minecraft-backup.sh'

# Check backup log
ssh docker-host2 'tail -20 ~/minecraft-backup.log'

# List backups on TrueNAS
sshpass -p 'GrilledCh33s3#' ssh -o StrictHostKeyChecking=no hutson@10.10.10.200 \
  'ls -lh /mnt/vault/users/backups/minecraft/'
```

### Restore from Backup

```bash
# 1. Stop the server in Crafty web UI

# 2. Copy backup from TrueNAS
sshpass -p 'GrilledCh33s3#' scp -o StrictHostKeyChecking=no \
  hutson@10.10.10.200:/mnt/vault/users/backups/minecraft/hutworld-YYYY-MM-DD_HHMM.tar.gz \
  /tmp/

# 3. Extract to server directory (backup existing first)
ssh docker-host2 'cd ~/crafty/data/servers && \
  mv 19f604a9-f037-442d-9283-0761c73cfd60 19f604a9-f037-442d-9283-0761c73cfd60.old && \
  tar -xzf /tmp/hutworld-YYYY-MM-DD_HHMM.tar.gz'

# 4. Start server in Crafty web UI
```

---

## Common Tasks

### Start/Stop Server

Via Crafty web UI at https://mc.htsn.io, or:

```bash
# Check Crafty container status
ssh docker-host2 'docker ps | grep crafty'

# Restart Crafty container
ssh docker-host2 'cd ~/crafty && docker compose restart'

# View Crafty logs
ssh docker-host2 'docker logs -f crafty'
```

### Backup Server

See [Backup Configuration](#backup-configuration) for full details.

```bash
# Run backup manually
ssh docker-host2 '~/minecraft-backup.sh'

# Check recent backups
sshpass -p 'GrilledCh33s3#' ssh -o StrictHostKeyChecking=no hutson@10.10.10.200 \
  'ls -lht /mnt/vault/users/backups/minecraft/ | head -5'
```

### Update Plugins

1. Download new plugin JAR
2. Upload via Crafty Files tab, or:
```bash
scp plugin.jar docker-host2:~/crafty/data/servers/hutworld/plugins/
```
3. Restart server in Crafty

### Check Server Logs

Via Crafty web UI (Logs tab), or:
```bash
ssh docker-host2 'tail -f ~/crafty/data/servers/hutworld/logs/latest.log'
```

---

## Troubleshooting

### Server won't start

```bash
# Check Crafty container logs
ssh docker-host2 'docker logs crafty --tail 50'

# Check server logs
ssh docker-host2 'cat ~/crafty/data/servers/hutworld/logs/latest.log | tail -100'

# Check Java version in container
ssh docker-host2 'docker exec crafty java -version'
```

### Can't connect externally

1. Verify port forwarding is active:
```bash
ssh root@10.10.10.1 'iptables -t nat -L -n | grep 25565'
```

2. Test from external network:
```bash
nc -zv hutworld.htsn.io 25565
```

3. Check if server is listening:
```bash
ssh docker-host2 'netstat -tlnp | grep 25565'
```

### Bedrock players can't connect

1. Verify Geyser plugin is installed and enabled
2. Check Geyser config: `~/crafty/data/servers/hutworld/plugins/Geyser-Spigot/config.yml`
3. Ensure UDP 19132 is forwarded and not blocked

### LuckPerms missing users/permissions

If LuckPerms shows a fresh database (missing users like Suwan):

1. **Check if original database exists:**
```bash
ssh docker-host2 'ls -la ~/crafty/data/import/hutworld/plugins/LuckPerms/*.db'
```

2. **Restore from import backup:**
```bash
# Stop server in Crafty UI first
ssh docker-host2 'cp ~/crafty/data/import/hutworld/plugins/LuckPerms/luckperms-h2-v2.mv.db \
  ~/crafty/data/servers/19f604a9-f037-442d-9283-0761c73cfd60/plugins/LuckPerms/'
```

3. **Or restore from TrueNAS backup:**
```bash
# List available backups
sshpass -p 'GrilledCh33s3#' ssh -o StrictHostKeyChecking=no hutson@10.10.10.200 \
  'ls -lt /mnt/vault/users/backups/minecraft/'

# Extract LuckPerms database from backup
sshpass -p 'GrilledCh33s3#' scp hutson@10.10.10.200:/mnt/vault/users/backups/minecraft/hutworld-YYYY-MM-DD_HHMM.tar.gz /tmp/
tar -xzf /tmp/hutworld-*.tar.gz -C /tmp --strip-components=2 \
  '*/plugins/LuckPerms/luckperms-h2-v2.mv.db'
```

4. **Restart server in Crafty UI**

---

## Migration History

### 2026-01-04: Backup System

- Configured automated backups to TrueNAS every 6 hours
- Set 14-backup retention (~3.5 days of recovery points)
- Created backup script with compression and cleanup
- Storage: `/mnt/vault/users/backups/minecraft/`

### 2026-01-03: Server Fixes & Updates

**Updates:**
- Upgraded Paper from 1.21.5 to 1.21.11 (build 69)
- Updated GSit from 2.3.2 to 3.1.1
- Fixed corrupted LuckPerms JAR (re-downloaded 5.5.22)
- Restored original LuckPerms database with user permissions

**Cleanup:**
- Removed disabled plugins: Dynmap, Graves
- Removed orphaned data folders: GriefPreventionData, SilkSpawners_v2, Graves, ViaRewind

**Fixes:**
- Fixed memory allocation (was attempting 2TB, set to 2GB min / 4GB max)
- Fixed file permissions for Docker container access

### 2026-01-03: Initial Migration

**Source:** Windows PC (10.10.10.150) - D:\Minecraft\mcss\servers\hutworld

**Steps completed:**
1. Compressed hutworld folder on Windows (2.4GB zip)
2. Transferred via SCP to docker-host2
3. Unzipped to ~/crafty/data/import/hutworld
4. Downloaded Paper 1.21.5 JAR (later upgraded to 1.21.11)
5. Imported server into Crafty Controller
6. Configured port forwarding (updated existing 25565 rule, added 19132)
7. Created DNS record for hutworld.htsn.io

**Original MCSS config preserved:** `mcss_server_config.json`

---

## Related Documentation

- [IP Assignments](IP-ASSIGNMENTS.md) - Network configuration
- [Traefik](TRAEFIK.md) - Reverse proxy setup
- [VMs](VMS.md) - docker-host2 details
- [Gateway](GATEWAY.md) - UCG-Fiber configuration

---

## Resources

- [Crafty Controller Docs](https://docs.craftycontrol.com/)
- [Paper MC](https://papermc.io/)
- [Geyser MC](https://geysermc.org/)
- [LuckPerms](https://luckperms.net/)

---

**Last Updated:** 2026-01-05

---

## Migration History (Backrooms)

### 2026-01-05: Backrooms Server Created

- Created new Backrooms server in Crafty Controller
- Installed Paper 1.21.4 build 232 (recommended version for datapack)
- Installed The Backrooms datapack v2.2.0 from Modrinth
- DNS record created for backrooms.htsn.io
- Memory configured for 512MB-1.5GB (VM memory constrained)
- Server running on port 25566
- **Pending:** Port forwarding for external access