hutson/homelab-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Auto-sync: 20260105-122831

Browse Source
This commit is contained in:
Hutson
2026-01-05 12:28:33 -05:00
parent 56b82df497
commit eddd98c57f
17 changed files with 1770 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

478
MINECRAFT.md Normal file
View File

@@ -0,0 +1,478 @@
# Minecraft Server - Hutworld
Minecraft server running on docker-host2 via Crafty Controller 4.
---
## Quick Reference
| 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 |
---
## 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 API on UCG-Fiber (10.10.10.1):
| Rule Name | Port | Protocol | Destination |
|-----------|------|----------|-------------|
| Minecraft Java | 25565 | TCP/UDP | 10.10.10.207:25565 |
| Minecraft Bedrock | 19132 | UDP | 10.10.10.207:19132 |
---
## 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) |
**Note:** Game traffic (25565, 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-04