Add scripts/README.md

scripts/README.md

@@ -0,0 +1,117 @@
+# Scripts
+
+This directory contains operational scripts used by the Minecraft server Docker stack.
+These scripts handle **initialization**, **backup & restore**, and **server/world configuration** tasks.
+
+Some scripts are desgined to by run **automatically**, while others are intended to be run **manually by an administrator**.
+
+---
+
+## Overview
+
+| Script / File | Purpose | How It's Run |
+| ------------- | ------- | ------------ |
+| `init.sh` | Prepare Docker volumes and permissions | Automatically by the init container |
+| `backup.sh` | Create and prune server backups | Automatically (e.g. cron/systemd) |
+| `restore.sh` | Restore data from a backup | Manually |
+| `setup.sh` | Configure gamerules, time, weather, gamemode | Manually |
+| `creative` | Gamerule definitions for creative worlds | Read by `setup.sh` |
+| `survival` | Gamerule definitions for survival worlds | Read by `setup.sh` |
+
+---
+
+## Script Details
+
+### `init.sh`
+
+**Purpose:**
+Ensures that required directories exist inside named Docker volumes and that ownership/permissions are set correctly.
+
+This script is responsible for preparing the filesystem so that the Minecraft server and related containers can start without permission issues.
+
+**Execution:**
+- Run **only** by the init container
+- Executed **inside** the init container
+- Not intended to be run manually
+- Does not take any arguments
+
+---
+
+### `backup.sh`
+
+**Purpose:**
+Creates a complete backup of the Minecraft server's persistent data, including:
+
+- World save files
+- Plugin data
+- Mod data
+- Permissions database
+- Plot database
+- Whitelist database
+
+This script also handles **automatic pruning of old backups** once a configured maximum number of backups is reached.
+
+**Execution**
+- Intended to run automatically on a schedule
+- Typically triggered by a **cron job** or **systemd timer**
+- Must be run from the directory containing `compose.yml`
+- Does not take any arguments
+
+---
+
+### `restore.sh`
+
+**Purpose:**
+Restores data from an existing backup back into the live server.
+
+This script supports **partial restores**, allowing you to restore only specific components, such as:
+- A single world
+- Permissions database
+- Any combination of components
+
+It can also be used to **initialize a brand-new server instance from an existing backup**.
+
+**Execution:**
+- Run **manually**
+- Must be run from the directory containing `compose.yml`
+- Run `restore.sh help` for usage information
+
+---
+
+### `setup.sh`
+
+**Purpose:**
+Applies server-wide configuration to all worlds, including:
+
+- Gamerules
+- Game mode
+- Time
+- Weather
+
+This script is primarily intended for **initial server setup**, but can be re-run if settings are accidentally changed or need to be reapplied.
+
+**Execution:**
+- Run manually
+- Must be run from the directory containing `compose.yml`
+- Does not take any arguments
+
+---
+
+## Gamerule Definition Files
+
+### `creative`
+
+Contains a list of gamerules that should be applied to **creative-mode worlds**.
+
+- Read by `setup.sh`
+- Format: one gamerule per line (as expected by the script)
+
+---
+
+### `survival`
+
+Contains a list of gamerules that should be applied to **survival-mode worlds**.
+
+- Read by `setup.sh`
+- Format: one gamerule per line (as expected by the script)
+