JaniSoto/mcserver
SHA256
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

docs: overhaul repository documentation architecture and operational runbooks

Browse source 
- 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:
JaniSoto 2026-08-15 19:18:47 +00:00
parent 2a71ef6d12
commit f441c6b13c
5 changed files with 94 additions and 96 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
README.md
View file

@ -2,6 +2,12 @@
Mono-repo containing infrastructure baselines, operational runbooks, and instance profile specifications for containerized Minecraft servers. 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 ## Repository Architecture
```text ```text
@ -9,30 +15,21 @@ Mono-repo containing infrastructure baselines, operational runbooks, and instanc
├── .gitignore ├── .gitignore
├── README.md ├── README.md
├── docs/ ├── docs/
│ ├── infrastructure-base.md # Cloud VM, host OS, BBR, UFW, & Docker daemon baseline │ ├── infrastructure-base.md # Cloud VM, host OS, network, and storage baseline
│ └── operations-manual.md # Daily administration, RCON guide, log filtering, & clean state runbooks │ └── operations-manual.md # Administration, RCON commands, log filtering, and state runbooks
└── instances/ └── instances/
└── forge-1.20.1-survival/ # Instance profile (Forge 1.20.1) └── forge-1.20.1-survival/ # Forge 1.20.1 survival instance profile
├── README.md # Instance spec, Compose config, JVM flags, & Mod Manifest (62 mods) ├── README.md # Player joining guide, instance specs, and admin runbooks
├── mod-configs.md # Mod configuration matrix & validated TOML/JSON schemas ├── mod-configs.md # Mod configuration matrix and validated schemas
├── patches/ ├── patches/
│ └── lts-auth/ # LTS Auth source code & in-container build script │ └── lts-auth/ # Custom authentication mod source and build scripts
└── runtime/ # Active Docker runtime directory └── runtime/ # Active Docker deployment directory
├── docker-compose.yml # Production compose stack ├── console # Interactive admin console script
└── data/ # Minecraft server data volume ├── docker-compose.yml # Production Compose stack
└── data/ # Server data volume
``` ```
## Quick Start (Deploying Instance) ## Quick Navigation
1. Navigate to the instance runtime folder: * **Host Provisioning & Security**: See [Infrastructure Baseline](docs/infrastructure-base.md) for OCI configuration, UFW rules, and kernel network tuning.
```bash * **Server Administration**: See [Operations Manual](docs/operations-manual.md) for maintenance workflows, backup management, and troubleshooting.
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
```

10
docs/infrastructure-base.md
View file

@ -42,10 +42,10 @@ sudo sysctl --system
## 3. Host Ownership Safeguard ## 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 ```bash
sudo chown -R $USER:$USER ./data sudo chown -R $USER:$USER ~/mcserver
chmod -R u+rwX ./data 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: 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 ### Phase 1: OCI Console Allocation
1. In OCI Console, navigate to **Compute** $\rightarrow$ **Instances** $\rightarrow$ `[Your Instance]` $\rightarrow$ **Storage** / **Boot Volume**. 1. In OCI Console, navigate to **Compute** -> **Instances** -> `[Your Instance]` -> **Storage** / **Boot Volume**.
2. Select **View boot volume details** $\rightarrow$ **Edit**. 2. Select **View boot volume details** -> **Edit**.
3. Change volume size from `47 GB` up to `200 GB` and save. 3. Change volume size from `47 GB` up to `200 GB` and save.
### Phase 2: Live Kernel Rescan & Partition Growth (Ubuntu) ### Phase 2: Live Kernel Rescan & Partition Growth (Ubuntu)

33
docs/operations-manual.md
View file

@ -14,13 +14,15 @@ When performing world resets or maintenance, classify directories according to t
| Category | Directory / File Path | Purpose | Action on Reset | | 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/mods/` | Server mod JAR files | **Preserve** |
| **Immutable** | `data/automodpack/` | AutoModpack configuration & client host payload | **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** | | **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/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/logs/` | Server console log files | Safe to purge |
| **Volatile** | `data/crash-reports/` | Crash stack traces | Safe to purge | | **Volatile** | `data/crash-reports/` | Crash stack traces | Safe to purge |
| **Volatile** | `data/simplebackups/` | World backup archives | Store or purge | | **Volatile** | `data/simplebackups/` | World backup archives | Store or purge |
@ -49,14 +51,15 @@ docker start $INSTANCE_NAME
### Full Nuclear Server Reset ### Full Nuclear Server Reset
```bash ```bash
docker compose down 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 docker compose up -d
``` ```
### Host File Ownership Recovery ### Host File Ownership Recovery
Reclaim ownership if Git operations or container permissions hit `Permission denied`:
```bash ```bash
sudo chown -R $USER:$USER ./data sudo chown -R $USER:$USER ~/mcserver
chmod -R u+rwX ./data 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 ```bash
docker exec -i $INSTANCE_NAME rcon-cli "spark profiler --timeout 30" docker exec -i $INSTANCE_NAME rcon-cli "spark profiler --timeout 30"
docker exec -i $INSTANCE_NAME rcon-cli "spark healthreport" docker exec -i $INSTANCE_NAME rcon-cli "spark healthreport"
``` ```
### Moderation & Player Control #### Moderation & Player Control
```bash ```bash
docker exec -i $INSTANCE_NAME rcon-cli "whitelist add <player>" 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 "whitelist remove <player>"

98
instances/forge-1.20.1-survival/README.md
View file

@ -1,18 +1,33 @@
# Instance Specification: Forge 1.20.1 Survival Modpack # 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` * **Instance ID**: `forge-1.20.1-survival`
* **Container Name**: `mc_forge_server` * **Container Name**: `mc_forge_server`
* **Minecraft Version**: `1.20.1` * **Minecraft Version**: `1.20.1`
* **Mod Loader**: Forge (`47.4.10`) * **Mod Loader**: Forge (`47.4.10`)
* **Java Runtime**: OpenJDK 17 (`itzg/minecraft-server:java17`) * **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`) ### Production `docker-compose.yml` (`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`.
```yaml ```yaml
services: services:
@ -70,7 +85,7 @@ services:
--- ---
## 2. Server Mod Manifest (66 Mods) ## 3. Server Mod Manifest (66 Mods)
```text ```text
[forge]ctov-3.4.14.jar [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 ### Synchronization Rules (`automodpack-server.json`)
* Minecraft **1.20.1** with **Forge** loader. * **Served Directory**: `/mods/*.jar` (Streamed directly from server runtime mod storage).
* **1 Mod**: `automodpack-mc1.20.1-forge-4.0.6.jar` in `.minecraft/mods/`. * **Excluded Server-Only Mods**: `SimpleBackups`, `spark`, `antixray`, `doubledoors`, `Clumps`, `collective`, `lts_auth`, `improvedmobs`.
* **Forced Client File Sync**:
### Client-Only Host Payload (16 Mods) * `/servers.dat` (Pre-configures server list pointing to `mc.sotohome.top`).
Located in `runtime/data/automodpack/host-modpack/main/mods/` on the server and pushed to clients automatically: * `/options.txt` (Synchronizes FOV, graphics, keybinds, and resource pack order).
* `/config/**` (Synchronizes mod settings, including shader configs).
```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).
--- ---
## 4. Operational Runbooks & Administration ## 5. Operational Runbooks & Administration
### Updating Client Master Defaults (`options.txt` / `servers.dat`) ### Interactive Console Dashboard (`runtime/console`)
From your local client instance terminal: To launch live container logs alongside an interactive RCON prompt:
```bash ```bash
cd ~/.local/share/PrismLauncher/instances/<instance_name>/minecraft cd instances/forge-1.20.1-survival/runtime
scp options.txt servers.dat ubuntu@sotoserver:~/mcserver/instances/forge-1.20.1-survival/runtime/data/automodpack/host-modpack/main/ ./console
ssh sotoserver "docker restart mc_forge_server"
``` ```
* **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`): 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. 1. Ensure container `mc_forge_server` is running.
2. Navigate to the patch directory and run the compilation script: 2. Execute the compilation script:
```bash ```bash
cd patches/lts-auth/ cd patches/lts-auth/
python3 build.py python3 build.py
``` ```
3. Restart the server container to load the updated JAR: 3. Restart the server container to load the compiled JAR:
```bash ```bash
docker restart mc_forge_server 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 radius 4000"
docker exec -i mc_forge_server rcon-cli "chunky quiet 10" 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 start"
docker exec -i mc_forge_server rcon-cli "chunky progress"
``` ```
### Performance Profiling (spark) ### Performance Profiling (spark)

8
instances/forge-1.20.1-survival/mod-configs.md
View file

@ -1,4 +1,4 @@
# Mod Configurations Matrix & Schemas # Mod Configuration Matrix & Schemas
## Summary Matrix ## Summary Matrix
@ -7,14 +7,14 @@
| Mod | Config File Path | Key Setting | Value | Purpose | | 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 | | **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 | | **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`) | | **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) | | **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 | | **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 | | **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 | | **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 & universe-wide cave mapping disabled | | **JourneyMap** | `runtime/data/journeymap/server/6.0/` | `playerRadarEnabled` / `caveMapping` | `"false"` / `"NONE"` | Server-enforced entity radar restrictions & cave mapping disabled |
--- ---