mcserver/docs/operations-manual.md

Server Operations & Administration Manual

1. Instance Target Context

Set the active container target in your shell session:

export INSTANCE_NAME="mc_forge_server"

---

2. Data Preservation Reference Matrix

When performing world resets or maintenance, classify directories according to this matrix:

Category	Directory / File Path	Purpose	Action on Reset
Tracked in Git	data/config/	Mod configuration files (backed up to repository)	Preserve
Immutable	data/mods/	Server mod JAR files	Preserve
Immutable	data/automodpack/	AutoModpack configuration & client host payload	Preserve
Immutable	data/eula.txt	EULA agreement file	Preserve
GitIgnored Secret	data/server.properties	Generated server settings (contains RCON password)	Rebuilt on boot
GitIgnored Secret	.env	Container environment variables	Preserve
GitIgnored Runtime	data/config/lts_auth/players.json	LTS Auth player account credentials	Delete on full reset
GitIgnored Runtime	data/config/fiw-mods-api/profiles/	FIW anti-cheat player profiles	Delete on full reset
Volatile	data/world/	Dynamic terrain & player data	Delete to reset seed
Volatile	data/logs/	Server console log files	Safe to purge
Volatile	data/crash-reports/	Crash stack traces	Safe to purge
Volatile	data/simplebackups/	World backup archives	Store or purge
Volatile	data/.cache/	Mod resource cache	Safe to purge
Volatile	data/modernfix/	Structure cache files	Safe to purge

---

3. Lifecycle & Reset Workflows

Basic Container Controls

# Start server container
docker start $INSTANCE_NAME

# Gracefully stop server container
docker stop $INSTANCE_NAME

# Restart server container
docker restart $INSTANCE_NAME

Clean World Reset (Preserving Configs & Mods)

docker stop $INSTANCE_NAME
mv data/world data/world_backup_$(date +%Y%m%d_%H%M%S)
docker start $INSTANCE_NAME

Targeted Dimensional Wipes

docker stop $INSTANCE_NAME
rm -rf data/world/DIM-1    # Nether
rm -rf data/world/DIM1     # End
docker start $INSTANCE_NAME

Full Nuclear Server Reset

docker compose down
rm -rf data/world data/logs/* data/crash-reports/* data/.cache data/modernfix/structureCacheV1 data/usercache.json data/banned-players.json data/banned-ips.json data/ops.json data/config/lts_auth/players.json data/config/fiw-mods-api/profiles/
docker compose up -d

Host File Ownership Recovery

Reclaim ownership if Git operations or container permissions hit Permission denied:

sudo chown -R $USER:$USER ~/mcserver
chmod -R u+rwX ~/mcserver

---

4. Diagnostics & Telemetry

Container Status & Resource Usage

# Check container uptime & port mapping
docker ps -f "name=$INSTANCE_NAME" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Check real-time CPU & memory utilization
docker stats $INSTANCE_NAME --no-stream

Log Inspection Pipeline

# Live log tailing (last 100 lines + follow)
docker logs -f --tail 100 $INSTANCE_NAME

# Filtered log pipeline (Errors, Warnings, Exceptions & Failures)
docker logs $INSTANCE_NAME 2>&1 | grep -iE "ERROR|WARN|Exception|Fatal|Failed|Caused by" | tail -n 60

# Search logs for a specific keyword or mod name
docker logs $INSTANCE_NAME 2>&1 | grep -i "<keyword>"

---

5. Administration & Console Tools

Interactive Console Dashboard (runtime/console)

Launch the interactive tmux dashboard (live log tail + interactive RCON command prompt):

cd instances/forge-1.20.1-survival/runtime
./console

• Top Pane: Live container log output (docker logs -f).
• Bottom Pane: Interactive RCON shell (MC>).
• Detach: Press Ctrl+B, then D.

Universal RCON Commands

Performance Profiling (spark)

docker exec -i $INSTANCE_NAME rcon-cli "spark profiler --timeout 30"
docker exec -i $INSTANCE_NAME rcon-cli "spark healthreport"

Moderation & Player Control

docker exec -i $INSTANCE_NAME rcon-cli "whitelist add <player>"
docker exec -i $INSTANCE_NAME rcon-cli "whitelist remove <player>"
docker exec -i $INSTANCE_NAME rcon-cli "tp <player1> <player2>"
docker exec -i $INSTANCE_NAME rcon-cli "gamerule keepInventory true"
docker exec -i $INSTANCE_NAME rcon-cli "op <player>"
docker exec -i $INSTANCE_NAME rcon-cli "deop <player>"