From f441c6b13cba6faeea915258330533b177724f704aa3e0f681436cf3b8a79f4a Mon Sep 17 00:00:00 2001 From: JaniSoto Date: Sat, 15 Aug 2026 19:18:47 +0000 Subject: [PATCH] docs: overhaul repository documentation architecture and operational runbooks - Add active server instance matrix and quick navigation to root README - Add player quick join guide and release download steps to instance README - Update data preservation matrix in operations manual for tracked mod configs - Document interactive admin console script (runtime/console) - Fix host file ownership recovery runbooks across documentation --- README.md | 41 ++++---- docs/infrastructure-base.md | 10 +- docs/operations-manual.md | 33 +++++-- instances/forge-1.20.1-survival/README.md | 98 ++++++++----------- .../forge-1.20.1-survival/mod-configs.md | 8 +- 5 files changed, 94 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 976fc58..3222720 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,12 @@ Mono-repo containing infrastructure baselines, operational runbooks, and instance profile specifications for containerized Minecraft servers. +## Active Server Instances + +| Instance ID | Engine / Version | Status | Documentation & Player Guide | +| :--- | :--- | :--- | :--- | +| `forge-1.20.1-survival` | Forge 1.20.1 | Active | [Instance & Player Guide](instances/forge-1.20.1-survival/README.md) | + ## Repository Architecture ```text @@ -9,30 +15,21 @@ Mono-repo containing infrastructure baselines, operational runbooks, and instanc ├── .gitignore ├── README.md ├── docs/ -│ ├── infrastructure-base.md # Cloud VM, host OS, BBR, UFW, & Docker daemon baseline -│ └── operations-manual.md # Daily administration, RCON guide, log filtering, & clean state runbooks +│ ├── infrastructure-base.md # Cloud VM, host OS, network, and storage baseline +│ └── operations-manual.md # Administration, RCON commands, log filtering, and state runbooks └── instances/ - └── forge-1.20.1-survival/ # Instance profile (Forge 1.20.1) - ├── README.md # Instance spec, Compose config, JVM flags, & Mod Manifest (62 mods) - ├── mod-configs.md # Mod configuration matrix & validated TOML/JSON schemas + └── forge-1.20.1-survival/ # Forge 1.20.1 survival instance profile + ├── README.md # Player joining guide, instance specs, and admin runbooks + ├── mod-configs.md # Mod configuration matrix and validated schemas ├── patches/ - │ └── lts-auth/ # LTS Auth source code & in-container build script - └── runtime/ # Active Docker runtime directory - ├── docker-compose.yml # Production compose stack - └── data/ # Minecraft server data volume + │ └── lts-auth/ # Custom authentication mod source and build scripts + └── runtime/ # Active Docker deployment directory + ├── console # Interactive admin console script + ├── docker-compose.yml # Production Compose stack + └── data/ # Server data volume ``` -## Quick Start (Deploying Instance) +## Quick Navigation -1. Navigate to the instance runtime folder: - ```bash - cd instances/forge-1.20.1-survival/runtime - ``` -2. Start the container: - ```bash - docker compose up -d - ``` -3. Stream startup logs: - ```bash - docker logs -f mc_forge_server - ``` +* **Host Provisioning & Security**: See [Infrastructure Baseline](docs/infrastructure-base.md) for OCI configuration, UFW rules, and kernel network tuning. +* **Server Administration**: See [Operations Manual](docs/operations-manual.md) for maintenance workflows, backup management, and troubleshooting. diff --git a/docs/infrastructure-base.md b/docs/infrastructure-base.md index 2ccfd54..f9084b8 100644 --- a/docs/infrastructure-base.md +++ b/docs/infrastructure-base.md @@ -42,10 +42,10 @@ sudo sysctl --system ## 3. Host Ownership Safeguard -Ensure host user retains ownership of container data to prevent `PermissionError (EACCES)`: +Ensure host user retains ownership of repository files and container data volumes to prevent `PermissionError (EACCES)` or Git unlink failures: ```bash -sudo chown -R $USER:$USER ./data -chmod -R u+rwX ./data +sudo chown -R $USER:$USER ~/mcserver +chmod -R u+rwX ~/mcserver ``` --- @@ -55,8 +55,8 @@ chmod -R u+rwX ./data Oracle Cloud allows up to 200 GB of Always Free block volume storage per tenancy. To expand the default 47 GB boot volume on Ubuntu instances without reinstalling: ### Phase 1: OCI Console Allocation -1. In OCI Console, navigate to **Compute** $\rightarrow$ **Instances** $\rightarrow$ `[Your Instance]` $\rightarrow$ **Storage** / **Boot Volume**. -2. Select **View boot volume details** $\rightarrow$ **Edit**. +1. In OCI Console, navigate to **Compute** -> **Instances** -> `[Your Instance]` -> **Storage** / **Boot Volume**. +2. Select **View boot volume details** -> **Edit**. 3. Change volume size from `47 GB` up to `200 GB` and save. ### Phase 2: Live Kernel Rescan & Partition Growth (Ubuntu) diff --git a/docs/operations-manual.md b/docs/operations-manual.md index f9f8333..b7c6e4a 100644 --- a/docs/operations-manual.md +++ b/docs/operations-manual.md @@ -14,13 +14,15 @@ When performing world resets or maintenance, classify directories according to t | Category | Directory / File Path | Purpose | Action on Reset | | :--- | :--- | :--- | :--- | -| **Immutable** | `data/config/` | Mod configuration files (except player auth store) | **Preserve** | +| **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/server.properties` | Generated server settings | **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/config/lts_auth/players.json` | LTS Auth player account credentials | Delete on full reset | | **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 | @@ -49,14 +51,15 @@ 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 +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 ./data -chmod -R u+rwX ./data +sudo chown -R $USER:$USER ~/mcserver +chmod -R u+rwX ~/mcserver ``` --- @@ -75,17 +78,27 @@ docker ps -f "name=$INSTANCE_NAME" --format "table {{.Names}}\t{{.Status}}\t{{.P --- -## 5. Universal RCON Command Reference +## 5. Administration & Console Tools -> **Note**: For instance-specific mod commands (e.g., Distant Horizons pre-generation or FLAN claim reloads), refer to the specific instance's `README.md`. +### 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`. -### Performance Profiling (spark) +### 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 +#### Moderation & Player Control ```bash docker exec -i $INSTANCE_NAME rcon-cli "whitelist add " docker exec -i $INSTANCE_NAME rcon-cli "whitelist remove " diff --git a/instances/forge-1.20.1-survival/README.md b/instances/forge-1.20.1-survival/README.md index 3b300e1..223b881 100644 --- a/instances/forge-1.20.1-survival/README.md +++ b/instances/forge-1.20.1-survival/README.md @@ -1,18 +1,33 @@ # Instance Specification: Forge 1.20.1 Survival Modpack -## 1. Overview & Compose Profile +## 1. Player Quick Join Guide + +### Client Requirements +* **Minecraft Version**: `1.20.1` +* **Mod Loader**: Forge (`47.4.10`) +* **Required Client Mod**: `automodpack-mc1.20.1-forge-4.0.6.jar` + +### Installation Steps +1. Download **`automodpack-mc1.20.1-forge-4.0.6.jar`** from the **[Releases](../../../releases)** section of this repository. +2. Place the `.jar` file into your local `.minecraft/mods/` directory. +3. Launch Minecraft with your Forge 1.20.1 profile. +4. Select **Multiplayer** and connect to **`mc.sotohome.top`**. + +*(AutoModpack automatically synchronizes all required client mods, configuration files, and shader presets upon connection).* + +--- + +## 2. Overview & Compose Profile + * **Instance ID**: `forge-1.20.1-survival` * **Container Name**: `mc_forge_server` * **Minecraft Version**: `1.20.1` * **Mod Loader**: Forge (`47.4.10`) * **Java Runtime**: OpenJDK 17 (`itzg/minecraft-server:java17`) -* **Process User**: Container UID `1000` / GID `1000` (`ubuntu`) -> **JVM Flag Rule**: `-XX:+UnlockExperimentalVMOptions` must precede experimental flags in `JVM_OPTS` to avoid JVM start failure on OpenJDK 17. +> **JVM Flag Rule**: `-XX:+UnlockExperimentalVMOptions` must precede experimental Garbage Collection flags in `JVM_OPTS` to prevent JVM initialization failures on OpenJDK 17. -### `docker-compose.yml` Reference (`runtime/docker-compose.yml`) - -> **Execution Note**: Always execute compose commands from within the `runtime/` directory (`cd runtime && docker compose up -d`) to ensure `./data` correctly maps to `runtime/data`. +### Production `docker-compose.yml` (`runtime/docker-compose.yml`) ```yaml services: @@ -70,7 +85,7 @@ services: --- -## 2. Server Mod Manifest (66 Mods) +## 3. Server Mod Manifest (66 Mods) ```text [forge]ctov-3.4.14.jar @@ -143,68 +158,42 @@ YungsBetterStrongholds-1.20-Forge-4.0.3.jar --- -## 3. Client Distribution Architecture (AutoModpack) +## 4. Client Distribution Architecture (AutoModpack) -Client modpack synchronization is fully automated via **AutoModpack**. Clients do not need manual mod downloads or multi-file setup zips. +Client modpack synchronization is fully automated via **AutoModpack** running directly on the Minecraft server. -### Minimal Client Requirement -* Minecraft **1.20.1** with **Forge** loader. -* **1 Mod**: `automodpack-mc1.20.1-forge-4.0.6.jar` in `.minecraft/mods/`. - -### Client-Only Host Payload (16 Mods) -Located in `runtime/data/automodpack/host-modpack/main/mods/` on the server and pushed to clients automatically: - -```text -AmbientSounds_FORGE_v6.3.8_mc1.20.1.jar -BetterPingDisplay-1.20.1-1.1.jar -Connector-1.0.0-beta.49+1.20.1.jar -CreativeCore_FORGE_v2.12.39_mc1.20.1.jar -FTB-Teams-Offline-Enabler-forge-1.20.1-1.0.0.jar -PresenceFootsteps-1.20.1-1.9.1-beta.1.jar -TUTORIAL_DISABLE-1.0.0.jar -balm-forge-1.20.1-7.3.42.jar -continuity-3.0.0+1.20.1.forge.jar -embeddium-0.3.31+mc1.20.1.jar -entity_model_features-3.2.4-1.20.1-forge.jar -entity_texture_features_1.20.1-forge-7.1.jar -fabric-api-0.92.6+1.11.15+1.20.1.jar -oculus-mc1.20.1-1.8.0.jar -rubidium-extra-0.5.4.4+mc1.20.1-build.131.jar -sound-physics-remastered-forge-1.20.1-1.4.10.jar -``` - -### Server-Side Exclusions (8 Mods) -Explicitly excluded from syncing to clients via `syncedFiles` in `automodpack-server.json`: -`SimpleBackups`, `spark`, `antixray`, `doubledoors`, `Clumps`, `collective`, `lts_auth`, `improvedmobs`. - -### Forced Client Files -Automatically written to standard client paths upon connection (`forceCopyFilesToStandardLocation`): -* `/options.txt` (Master FOV, VSync, graphics, keybinds, and active resource pack array). -* `/servers.dat` (Pre-configured server list pointing to `mc.sotohome.top`). -* `/config/**` (Mod configurations, including `oculus.properties` for BSL shaders). +### Synchronization Rules (`automodpack-server.json`) +* **Served Directory**: `/mods/*.jar` (Streamed directly from server runtime mod storage). +* **Excluded Server-Only Mods**: `SimpleBackups`, `spark`, `antixray`, `doubledoors`, `Clumps`, `collective`, `lts_auth`, `improvedmobs`. +* **Forced Client File Sync**: + * `/servers.dat` (Pre-configures server list pointing to `mc.sotohome.top`). + * `/options.txt` (Synchronizes FOV, graphics, keybinds, and resource pack order). + * `/config/**` (Synchronizes mod settings, including shader configs). --- -## 4. Operational Runbooks & Administration +## 5. Operational Runbooks & Administration -### Updating Client Master Defaults (`options.txt` / `servers.dat`) -From your local client instance terminal: +### Interactive Console Dashboard (`runtime/console`) +To launch live container logs alongside an interactive RCON prompt: ```bash -cd ~/.local/share/PrismLauncher/instances//minecraft -scp options.txt servers.dat ubuntu@sotoserver:~/mcserver/instances/forge-1.20.1-survival/runtime/data/automodpack/host-modpack/main/ -ssh sotoserver "docker restart mc_forge_server" +cd instances/forge-1.20.1-survival/runtime +./console ``` +* **Top Window**: Live log stream (`docker logs -f mc_forge_server`). +* **Bottom Window**: Interactive RCON shell (`MC>`). +* **Detach**: Press `Ctrl+B`, then `D` (leaves container running in background). -### In-House Auth Mod Patch Compilation (`patches/lts-auth/`) +### In-House Auth Mod Compilation (`patches/lts-auth/`) To rebuild and hot-swap the custom authentication mod (`lts_auth-1.0.1+mc1.20.1.jar`) from source (`LtsAuthMod.java`, `LoginCommand.java`): -1. Ensure the container `mc_forge_server` is running. -2. Navigate to the patch directory and run the compilation script: +1. Ensure container `mc_forge_server` is running. +2. Execute the compilation script: ```bash cd patches/lts-auth/ python3 build.py ``` -3. Restart the server container to load the updated JAR: +3. Restart the server container to load the compiled JAR: ```bash docker restart mc_forge_server ``` @@ -216,7 +205,6 @@ docker exec -i mc_forge_server rcon-cli "chunky center 0 0" docker exec -i mc_forge_server rcon-cli "chunky radius 4000" docker exec -i mc_forge_server rcon-cli "chunky quiet 10" docker exec -i mc_forge_server rcon-cli "chunky start" -docker exec -i mc_forge_server rcon-cli "chunky progress" ``` ### Performance Profiling (spark) diff --git a/instances/forge-1.20.1-survival/mod-configs.md b/instances/forge-1.20.1-survival/mod-configs.md index a63ab09..6baddda 100644 --- a/instances/forge-1.20.1-survival/mod-configs.md +++ b/instances/forge-1.20.1-survival/mod-configs.md @@ -1,4 +1,4 @@ -# Mod Configurations Matrix & Schemas +# Mod Configuration Matrix & Schemas ## Summary Matrix @@ -7,14 +7,14 @@ | Mod | Config File Path | Key Setting | Value | Purpose | | :--- | :--- | :--- | :--- | :--- | | **AutoModpack** | `runtime/data/automodpack/automodpack-server.json` | `validateSecrets` / `forceCopyFilesToStandardLocation` | `false` / `["/mods/*.jar", "/servers.dat", "/options.txt", "/config/**"]` | Dynamic modpack delivery, trusted instant join, and forced client option sync | -| **LTS Auth** | `runtime/data/config/lts_auth/messages.yml` | `timeout_kick` | Configured message | In-game auth, invulnerability lock & auto-kick (`players.json` credential store) | +| **LTS Auth** | `runtime/data/config/lts_auth/messages.yml` | `timeout_kick` | Configured message | In-game auth, invulnerability lock & auto-kick (`players.json` credential store ignored by Git) | | **Locks Reforged** | `runtime/data/config/locks-common.toml` | `"Enable Loot-Scaled Locks"` | `true` | Loot-value-based container lock tier selection | | **Improved Mobs** | `runtime/data/config/improvedmobs/common.toml` | `"Breaker Chance"` / `"Stealer Chance"` | `0.0` / `0.3` | Disables block breaking; item stealing enabled (30%); JAR excluded from client sync (`!/mods/improvedmobs*.jar`) | | **Majrusz Difficulty** | `runtime/data/config/majruszsdifficulty.json` | `is_per_player_difficulty_enabled` | `true` | Isolated per-player milestone progression (`normal`, `expert`, `master` stages) | | **Create Addition** | `runtime/data/config/createaddition-common.toml` | `[alternator].generator_efficiency` | `0.5` | Tech power generation rebalance | | **Sophisticated Core** | `runtime/data/config/sophisticatedcore-common.toml` | `enabledItems` | Tier 3/4 upgrades = `false` | Cap portable storage capacity | -| **AntiXray** | `runtime/data/config/antixray.toml` | `enabled` / `[overworld].engineMode` | `false` / `3` | Global default disabled (prevents space/orbit bugs); Overworld Mode 3 & Nether Mode 1 active | -| **JourneyMap** | `runtime/data/journeymap/server/6.0/` | `playerRadarEnabled` / `caveMapping` | `"false"` / `"NONE"` | Server-enforced entity radar restrictions & universe-wide cave mapping disabled | +| **AntiXray** | `runtime/data/config/antixray.toml` | `enabled` / `[overworld].engineMode` | `false` / `3` | Global default disabled; Overworld Mode 3 & Nether Mode 1 active | +| **JourneyMap** | `runtime/data/journeymap/server/6.0/` | `playerRadarEnabled` / `caveMapping` | `"false"` / `"NONE"` | Server-enforced entity radar restrictions & cave mapping disabled | ---