diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..0ecc43f --- /dev/null +++ b/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) +