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
This commit is contained in:
parent
2a71ef6d12
commit
f441c6b13c
5 changed files with 94 additions and 96 deletions
41
README.md
41
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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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 <player>"
|
||||
docker exec -i $INSTANCE_NAME rcon-cli "whitelist remove <player>"
|
||||
|
|
|
|||
|
|
@ -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/<instance_name>/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)
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue