# Server Operations & Administration Manual

## 1. Instance Target Context
Set the active container target in your shell session:
```bash
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** |
| **Tracked in Git** | `data/automodpack/host-modpack/main/config/defaultoptions/` | Master client default options (`options.txt`) & keybindings (`keybindings.txt`) | **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
```bash
# 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)
```bash
docker stop $INSTANCE_NAME
mv data/world data/world_backup_$(date +%Y%m%d_%H%M%S)
docker start $INSTANCE_NAME
```

### Targeted Dimensional Wipes
```bash
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
```bash
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`:
```bash
sudo chown -R $USER:$USER ~/mcserver
chmod -R u+rwX ~/mcserver
```

---

## 4. Diagnostics & Telemetry

### Container Status & Resource Usage
```bash
# 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
```bash
# 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):
```bash
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)
```bash
docker exec -i $INSTANCE_NAME rcon-cli "spark profiler --timeout 30"
docker exec -i $INSTANCE_NAME rcon-cli "spark healthreport"
```

#### Moderation & Player Control
```bash
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>"
```