From 1078bb4dfbc5df5bdd47b816547f9ebeafcfe641 Mon Sep 17 00:00:00 2001 From: Matthew Anderson Date: Sat, 19 Sep 2026 00:26:38 -0500 Subject: [PATCH 1/2] docs: consolidate documentation and AI config, remove dead files Documentation - Rewrite README.md: fix broken root-level links (DEVELOPMENT.md, ROADMAP.md), point to the systemd units actually shipped in systemd/ instead of a hand-written one, and document .env configuration. - Rewrite docs/INDEX.md as a task-oriented index of all 48 guides; docs/README.md and tests/README.md become pointers rather than competing structure listings. - Merge RESTART_LOOP_TROUBLESHOOTING.md and DOCKER_COMPOSE_FIX.md into docs/TROUBLESHOOTING.md, and TEST_COVERAGE.md into docs/TESTING.md. - Delete 15 historical process docs plus all of docs/archive/ (17 files); that record lives in CHANGELOG.md and git history. AI configuration - Add AGENTS.md as the single source of truth, following the ai-template-repo convention. It replaces AGENT_INSTRUCTIONS.md and the 317-line .cursorrules, which duplicated each other, and corrects what both got wrong: the auth decorator is @require_permission(""), scripts source scripts/lib/common.sh rather than redefining colors and PROJECT_DIR, and this repo uses npm rather than pnpm. - Add CLAUDE.md, .cursor/rules/project.mdc, .clinerules, .windsurfrules and .github/copilot-instructions.md as thin pointers; reduce .cursorrules to one. Dead files - Remove root .eslintrc.json and .eslintignore: linting runs inside web/, whose .eslintrc.cjs sets root: true, so neither was ever read. - Remove root playwright.config.js and tests/e2e/browser/: stale duplicates of web/playwright.config.js and web/tests/e2e/, as that directory's own README already noted. - Remove web/playwright-report/index.html, a 520 KB generated report. Correctness - Fix 160 references to ./manage.sh and 5 to ./setup-rpi.sh; neither file exists at the repo root and nothing creates them. - Use "docker compose" rather than "docker-compose" throughout, matching the Makefile's COMPOSE detection and the systemd units. - Add .env.example, which the Makefile told users to copy but did not exist. - Sync pytest markers in pyproject.toml with tests/api/pytest.ini, which was missing performance, contract and e2e; --strict-markers would have failed a run started from the repo root. Drop the duplicate [tool.coverage] block so .coverage-config.ini is the only coverage config. - .gitignore: add .mypy_cache/, playwright-report/, test-results/, and fix "!server.jar # comment" -- gitignore has no inline comments, so that pattern matched a literal filename. Verified: docker compose config validates, all scripts pass bash -n, eslint is clean, 221 pytest tests pass at 42% coverage (threshold 40%), 144 Vitest tests pass, and 0 internal markdown links are broken. Co-Authored-By: Claude Opus 5 --- .clinerules | 6 + .cursor/rules/project.mdc | 9 + .cursorrules | 321 +------- .env.example | 20 + .eslintignore | 8 - .eslintrc.json | 37 - .github/copilot-instructions.md | 13 + .gitignore | 17 +- .windsurfrules | 6 + AGENTS.md | 207 +++++ AGENT_INSTRUCTIONS.md | 735 ------------------ CHANGELOG.md | 45 ++ CLAUDE.md | 15 + CONTRIBUTING.md | 6 +- README.md | 534 ++++--------- docs/ADVANCED_OPTIMIZATIONS.md | 290 ------- docs/API_KEYS.md | 2 +- docs/CI_CD.md | 2 +- docs/CLEANUP_OPTIMIZATIONS_SUMMARY.md | 165 ---- docs/CLOUD_BACKUP.md | 4 +- docs/CONFIGURATION_EXAMPLES.md | 12 +- docs/CONSOLIDATION_SUMMARY.md | 262 ------- docs/CURSOR_CONFIGURATION.md | 21 +- docs/DEVELOPMENT.md | 4 +- docs/DOCKER_COMPOSE_FIX.md | 147 ---- docs/DOCUMENTATION_CONSOLIDATION_PLAN.md | 119 --- docs/INDEX.md | 273 ++----- docs/INSTALL.md | 22 +- docs/LINTING.md | 2 +- docs/LOG_MANAGEMENT.md | 52 +- docs/MINECRAFT_MANAGEMENT.md | 2 +- docs/MINECRAFT_SERVER_SETUP.md | 14 +- docs/MOD_SUPPORT.md | 6 +- docs/MULTI_ARCHITECTURE.md | 12 +- docs/MULTI_WORLD.md | 70 +- docs/OPTIMIZATION_COMPLETE.md | 156 ---- docs/OPTIMIZATION_SUMMARY.md | 202 ----- docs/PERFORMANCE_BENCHMARKING.md | 2 +- docs/QUICK_REFERENCE.md | 60 +- docs/RASPBERRY_PI_COMPATIBILITY.md | 16 +- docs/RASPBERRY_PI_OPTIMIZATIONS.md | 4 +- docs/RBAC.md | 2 +- docs/README.md | 100 +-- docs/RESTART_LOOP_TROUBLESHOOTING.md | 251 ------ docs/SETUP_CHECKLIST.md | 313 -------- docs/TESTING.md | 58 +- docs/TEST_COVERAGE.md | 320 -------- docs/TROUBLESHOOTING.md | 151 +++- docs/WORKSPACE_ENHANCEMENTS.md | 219 ------ docs/archive/API_DOCUMENTATION.md | 327 -------- docs/archive/CI_CD_ENHANCEMENTS.md | 288 ------- docs/archive/CI_CD_OPTIMIZATIONS.md | 261 ------- docs/archive/CI_CD_PIPELINE.md | 243 ------ docs/archive/CONSOLIDATION_NOTES.md | 120 --- docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md | 356 --------- docs/archive/GAMEPLAY_FEATURES_IMPLEMENTED.md | 221 ------ docs/archive/IMPLEMENTATION_SUMMARY.md | 262 ------- docs/archive/IMPLEMENTATION_SUMMARY_P1.md | 275 ------- docs/archive/IMPLEMENTATION_SUMMARY_docs.md | 262 ------- docs/archive/README.md | 47 -- docs/archive/RPI5_ACTION_CHECKLIST.md | 140 ---- docs/archive/RPI5_OPTIMIZATIONS_SUMMARY.md | 257 ------ docs/archive/SUMMARY.md | 371 --------- docs/archive/TESTING_COMPLETE.md | 403 ---------- docs/archive/TESTING_ENHANCEMENTS.md | 372 --------- docs/archive/TESTING_FINAL_SUMMARY.md | 243 ------ playwright.config.js | 41 - pyproject.toml | 25 +- tests/ANALYTICS_TESTS.md | 187 ----- tests/COMPLETE_TEST_SUMMARY.md | 325 -------- tests/README.md | 203 +---- tests/TEST_SUMMARY.md | 234 ------ tests/e2e/browser/README.md | 134 ---- tests/e2e/browser/analytics.spec.js | 150 ---- tests/e2e/browser/user-journey.spec.js | 88 --- tests/e2e/browser/visual-regression.spec.js | 79 -- web/playwright-report/index.html | 85 -- 77 files changed, 910 insertions(+), 10403 deletions(-) create mode 100644 .clinerules create mode 100644 .cursor/rules/project.mdc create mode 100644 .env.example delete mode 100644 .eslintignore delete mode 100644 .eslintrc.json create mode 100644 .github/copilot-instructions.md create mode 100644 .windsurfrules create mode 100644 AGENTS.md delete mode 100644 AGENT_INSTRUCTIONS.md create mode 100644 CLAUDE.md delete mode 100644 docs/ADVANCED_OPTIMIZATIONS.md delete mode 100644 docs/CLEANUP_OPTIMIZATIONS_SUMMARY.md delete mode 100644 docs/CONSOLIDATION_SUMMARY.md delete mode 100644 docs/DOCKER_COMPOSE_FIX.md delete mode 100644 docs/DOCUMENTATION_CONSOLIDATION_PLAN.md delete mode 100644 docs/OPTIMIZATION_COMPLETE.md delete mode 100644 docs/OPTIMIZATION_SUMMARY.md delete mode 100644 docs/RESTART_LOOP_TROUBLESHOOTING.md delete mode 100644 docs/SETUP_CHECKLIST.md delete mode 100644 docs/TEST_COVERAGE.md delete mode 100644 docs/WORKSPACE_ENHANCEMENTS.md delete mode 100644 docs/archive/API_DOCUMENTATION.md delete mode 100644 docs/archive/CI_CD_ENHANCEMENTS.md delete mode 100644 docs/archive/CI_CD_OPTIMIZATIONS.md delete mode 100644 docs/archive/CI_CD_PIPELINE.md delete mode 100644 docs/archive/CONSOLIDATION_NOTES.md delete mode 100644 docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md delete mode 100644 docs/archive/GAMEPLAY_FEATURES_IMPLEMENTED.md delete mode 100644 docs/archive/IMPLEMENTATION_SUMMARY.md delete mode 100644 docs/archive/IMPLEMENTATION_SUMMARY_P1.md delete mode 100644 docs/archive/IMPLEMENTATION_SUMMARY_docs.md delete mode 100644 docs/archive/README.md delete mode 100644 docs/archive/RPI5_ACTION_CHECKLIST.md delete mode 100644 docs/archive/RPI5_OPTIMIZATIONS_SUMMARY.md delete mode 100644 docs/archive/SUMMARY.md delete mode 100644 docs/archive/TESTING_COMPLETE.md delete mode 100644 docs/archive/TESTING_ENHANCEMENTS.md delete mode 100644 docs/archive/TESTING_FINAL_SUMMARY.md delete mode 100644 playwright.config.js delete mode 100644 tests/ANALYTICS_TESTS.md delete mode 100644 tests/COMPLETE_TEST_SUMMARY.md delete mode 100644 tests/TEST_SUMMARY.md delete mode 100644 tests/e2e/browser/README.md delete mode 100644 tests/e2e/browser/analytics.spec.js delete mode 100644 tests/e2e/browser/user-journey.spec.js delete mode 100644 tests/e2e/browser/visual-regression.spec.js delete mode 100644 web/playwright-report/index.html diff --git a/.clinerules b/.clinerules new file mode 100644 index 0000000..8e80418 --- /dev/null +++ b/.clinerules @@ -0,0 +1,6 @@ +# POINTER FILE — single source of truth is /AGENTS.md at the repo root. +# Edit AGENTS.md, not this file. + +Follow the project guidelines defined in the root AGENTS.md file: +stack, commands, code style, architecture, testing, Raspberry Pi +constraints, security, and git conventions are all defined there. diff --git a/.cursor/rules/project.mdc b/.cursor/rules/project.mdc new file mode 100644 index 0000000..f758ce7 --- /dev/null +++ b/.cursor/rules/project.mdc @@ -0,0 +1,9 @@ +--- +description: Project guidelines — single source of truth is /AGENTS.md +alwaysApply: true +--- + +Follow the project guidelines defined in the root AGENTS.md file: +stack, commands, code style, architecture, testing, Raspberry Pi +constraints, security, and git conventions are all defined there. +Edit AGENTS.md, not this file. diff --git a/.cursorrules b/.cursorrules index 4a036f5..8e80418 100644 --- a/.cursorrules +++ b/.cursorrules @@ -1,317 +1,6 @@ -# Minecraft Server Management - Agent Instructions +# POINTER FILE — single source of truth is /AGENTS.md at the repo root. +# Edit AGENTS.md, not this file. -## Project Overview - -This is a Minecraft server management system optimized for Raspberry Pi 5 (ARM64), providing Docker-based deployment, automated backups, plugin management, multi-world support, REST API, and a React web interface. - -## Architecture - -### Technology Stack - -- **Backend API**: Python 3 with Flask (REST API for server management) -- **Frontend**: React with Vite, Tailwind CSS -- **Server Management**: Bash scripts for server operations -- **Containerization**: Docker & Docker Compose -- **Target Platform**: Raspberry Pi 5 (ARM64), but supports x86_64 -- **Testing**: pytest for Python, Vitest for React, BATS for shell scripts - -### Project Structure - -``` -minecraft/ -├── api/ # Python Flask REST API -│ ├── server.py # Main API server -│ └── requirements.txt # Python dependencies -├── web/ # React frontend -│ ├── src/ # React source code -│ └── package.json # Node dependencies -├── scripts/ # Shell scripts for server management -│ ├── manage.sh # Main management script -│ ├── backup-scheduler.sh -│ ├── plugin-manager.sh -│ └── ... -├── config/ # Configuration files -│ ├── api.conf # API configuration -│ └── *.conf # Various config files -├── docs/ # Documentation -├── tests/ # Test suites -│ ├── api/ # Python API tests -│ ├── integration/ # Integration tests -│ └── unit/ # Unit tests -├── docker-compose.yml # Docker Compose configuration -├── Dockerfile # Docker image definition -├── Makefile # Convenience commands -└── README.md # Main documentation -``` - -## Code Standards - -### Shell Scripts - -- **Shebang**: Always use `#!/bin/bash` -- **Error Handling**: Use `set -e` at the start -- **Indentation**: 4 spaces (not tabs) -- **Variables**: Always quote variables: `"$VAR"` not `$VAR` -- **Functions**: Use functions for repeated code -- **Colors**: Use ANSI color codes for output (RED, GREEN, YELLOW, BLUE, NC) -- **Comments**: Add comments for complex logic -- **Syntax Check**: Run `bash -n script.sh` before committing - -Example: - -```bash -#!/bin/bash -set -e - -RED='\033[0;31m' -GREEN='\033[0;32m' -NC='\033[0m' - -function example_function() { - local param="$1" - echo -e "${GREEN}Processing: $param${NC}" -} -``` - -### Python Code - -- **Style**: Follow PEP 8 -- **Type Hints**: Use type hints where appropriate -- **Docstrings**: Include docstrings for functions and classes -- **Error Handling**: Use try/except with specific exceptions -- **Imports**: Group imports (stdlib, third-party, local) -- **Path Handling**: Use `pathlib.Path` for file paths - -Example: - -```python -from pathlib import Path -from typing import Optional - -def example_function(param: str) -> Optional[Path]: - """Process parameter and return path.""" - try: - path = Path(param) - return path if path.exists() else None - except Exception as e: - print(f"Error: {e}") - return None -``` - -### React/JavaScript - -- **Framework**: React with functional components and hooks -- **Styling**: Tailwind CSS for styling -- **Testing**: Vitest for unit tests -- **API Calls**: Use services/api.js for API communication -- **Components**: Keep components small and focused -- **State Management**: Use React hooks (useState, useEffect) - -### Docker - -- **Base Images**: Use official images when possible -- **Multi-stage**: Use multi-stage builds for optimization -- **Layers**: Minimize layers, clean up in same layer -- **Environment Variables**: Use .env files and docker-compose.yml -- **Health Checks**: Include healthcheck in docker-compose.yml - -### YAML Files - -- **Indentation**: 2 spaces -- **Environment Variables**: Use `${VAR:-default}` syntax -- **Validation**: Run `docker-compose config` to validate - -## Development Workflow - -### Making Changes - -1. Create feature branch: `git checkout -b feature/feature-name` -2. Make changes following code standards -3. Test changes thoroughly -4. Update documentation if needed -5. Commit with clear messages: `git commit -m "Add feature: description"` -6. Push and create PR - -### Testing Requirements - -- **Shell Scripts**: Run `bash -n script.sh` for syntax check -- **Python**: Run `pytest tests/api/ -v` for API tests -- **React**: Run `npm test` for frontend tests -- **Docker**: Run `docker-compose config` to validate -- **Integration**: Test on Raspberry Pi 5 when possible - -### Documentation - -- **Update README.md** for user-facing changes -- **Update relevant docs/** files for feature changes -- **Update CHANGELOG.md** for all changes -- **Add examples** to CONFIGURATION_EXAMPLES.md when adding config options -- **Update QUICK_REFERENCE.md** when adding commands - -## Important Considerations - -### Raspberry Pi 5 Optimization - -- **Memory**: Be mindful of memory constraints (4GB/8GB models) -- **CPU**: ARM64 architecture, optimize for efficiency -- **Storage**: Consider SD card write limits -- **Performance**: Test on actual hardware when possible - -### Docker Best Practices - -- **Resource Limits**: Set appropriate memory limits in docker-compose.yml -- **Volumes**: Use named volumes or bind mounts appropriately -- **Networking**: Use custom networks for isolation -- **Logging**: Configure log rotation to prevent disk fill - -### Security - -- **API Keys**: Store in config/api-keys.json, never commit secrets -- **RCON**: Use secure passwords, generate randomly -- **File Permissions**: Ensure proper permissions on scripts and configs -- **Input Validation**: Validate all user inputs in API - -### Error Handling - -- **Graceful Degradation**: Handle missing dependencies gracefully -- **User Feedback**: Provide clear error messages -- **Logging**: Log errors with context -- **Recovery**: Implement rollback mechanisms where appropriate - -## Common Patterns - -### Script Structure - -```bash -#!/bin/bash -set -e - -# Colors -RED='\033[0;31m' -GREEN='\033[0;32m' -NC='\033[0m' - -# Script directory -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -# Functions -function main_function() { - # Implementation -} - -# Main execution -if [ "$#" -eq 0 ]; then - usage - exit 1 -fi - -case "$1" in - command) - main_function - ;; - *) - usage - exit 1 - ;; -esac -``` - -### API Endpoint Pattern - -```python -@app.route('/api/endpoint', methods=['GET']) -@require_api_key -def endpoint(): - """Endpoint description.""" - try: - # Implementation - return jsonify({"status": "success", "data": result}) - except Exception as e: - return jsonify({"status": "error", "message": str(e)}), 500 -``` - -### React Component Pattern - -```jsx -import { useState, useEffect } from 'react'; -import { api } from '../services/api'; - -export function Component() { - const [data, setData] = useState(null); - - useEffect(() => { - api.getData().then(setData); - }, []); - - return
{/* Component JSX */}
; -} -``` - -## File Naming Conventions - -- **Scripts**: `kebab-case.sh` (e.g., `backup-scheduler.sh`) -- **Python**: `snake_case.py` (e.g., `server.py`) -- **React**: `PascalCase.jsx` for components (e.g., `StatusCard.jsx`) -- **Config**: `kebab-case.conf` (e.g., `backup-schedule.conf`) -- **Documentation**: `UPPERCASE.md` (e.g., `README.md`) - -## Testing Standards - -- **Unit Tests**: Test individual functions/components -- **Integration Tests**: Test script interactions -- **API Tests**: Test all endpoints with pytest -- **Coverage**: Aim for >50% coverage (currently at 51%) -- **Test Files**: Mirror source structure in `tests/` directory - -## Documentation Standards - -- **Markdown**: Use Markdown for all documentation -- **Code Examples**: Include working code examples -- **Links**: Keep internal links relative -- **Structure**: Use clear headings and sections -- **Updates**: Update docs when making changes - -## Git Workflow - -- **Branches**: Use `feature/`, `fix/`, `docs/` prefixes -- **Commits**: Clear, descriptive commit messages -- **PRs**: One feature/fix per PR -- **Reviews**: Address feedback before merging - -## When Adding New Features - -1. **Check TASKS.md** for related tasks -2. **Follow existing patterns** in similar features -3. **Add tests** for new functionality -4. **Update documentation** (README, relevant docs/) -5. **Update CHANGELOG.md** with changes -6. **Test on Raspberry Pi 5** if hardware-specific - -## Common Commands - -- `./manage.sh start` - Start server -- `./manage.sh stop` - Stop server -- `make test` - Run tests -- `make build` - Build Docker image -- `docker-compose logs` - View logs -- `pytest tests/api/ -v` - Run API tests - -## Key Files to Know - -- `scripts/manage.sh` - Main management script -- `api/server.py` - REST API server -- `docker-compose.yml` - Docker configuration -- `README.md` - Main documentation -- `TASKS.md` - Development tasks -- `CONTRIBUTING.md` - Contribution guidelines - -## Remember - -- Always test on Raspberry Pi 5 when possible -- Keep memory usage in mind (4GB/8GB models) -- Follow existing code patterns -- Update documentation with changes -- Write tests for new features -- Use clear, descriptive names -- Handle errors gracefully -- Provide user feedback +Follow the project guidelines defined in the root AGENTS.md file: +stack, commands, code style, architecture, testing, Raspberry Pi +constraints, security, and git conventions are all defined there. diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..090bbc7 --- /dev/null +++ b/.env.example @@ -0,0 +1,20 @@ +# Copy to .env and adjust. Docker Compose reads .env automatically; .env itself is +# gitignored. Every value below is optional — the defaults shown are what +# docker-compose.yml falls back to. + +# --- Minecraft server ------------------------------------------------------ +MINECRAFT_VERSION=1.20.4 +SERVER_TYPE=vanilla # vanilla | paper | spigot | fabric | forge +SERVER_PORT=25565 +EULA=TRUE # you must accept https://www.minecraft.net/eula +TZ=UTC + +# --- Memory ---------------------------------------------------------------- +# 4GB Pi 5: MEMORY_MIN=1G MEMORY_MAX=2G CONTAINER_MEMORY_LIMIT=3G +# 8GB Pi 5: MEMORY_MIN=2G MEMORY_MAX=4G CONTAINER_MEMORY_LIMIT=5G +# +# CONTAINER_MEMORY_LIMIT must exceed MEMORY_MAX by roughly 0.5-1G: the JVM needs +# headroom beyond the heap. Setting it equal to MEMORY_MAX causes a restart loop. +MEMORY_MIN=1G +MEMORY_MAX=2G +CONTAINER_MEMORY_LIMIT=3G diff --git a/.eslintignore b/.eslintignore deleted file mode 100644 index 80b63c5..0000000 --- a/.eslintignore +++ /dev/null @@ -1,8 +0,0 @@ -node_modules/ -dist/ -build/ -coverage/ -*.config.js -vite.config.js -vitest.config.js - diff --git a/.eslintrc.json b/.eslintrc.json deleted file mode 100644 index 958aa9d..0000000 --- a/.eslintrc.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "env": { - "browser": true, - "es2021": true, - "node": true - }, - "extends": [ - "eslint:recommended", - "plugin:react/recommended", - "plugin:react-hooks/recommended" - ], - "parserOptions": { - "ecmaVersion": "latest", - "sourceType": "module", - "ecmaFeatures": { - "jsx": true - } - }, - "plugins": ["react", "react-hooks", "react-refresh"], - "rules": { - "react/react-in-jsx-scope": "off", - "react/prop-types": "warn", - "react-hooks/rules-of-hooks": "error", - "react-hooks/exhaustive-deps": "warn", - "react-refresh/only-export-components": [ - "warn", - { "allowConstantExport": true } - ], - "no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }], - "no-console": ["warn", { "allow": ["warn", "error"] }] - }, - "settings": { - "react": { - "version": "detect" - } - } -} diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..dfb9881 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,13 @@ +# Project Guidelines + + + +Follow the instructions in the root `AGENTS.md` file: stack, commands, code style, +architecture, testing, Raspberry Pi constraints, security, and git conventions are +all defined there. + +Copilot-specific additions only below this line. diff --git a/.gitignore b/.gitignore index fc29b0b..e40552c 100644 --- a/.gitignore +++ b/.gitignore @@ -6,8 +6,10 @@ plugins/ # Configuration files with secrets .env config/*.conf +config/*.json +config/audit.log !config/README.md -!config/examples/ +!config/*.conf.example # Temporary files *.log @@ -32,7 +34,8 @@ docker-volumes/ # Build artifacts *.jar -!server.jar # Keep server.jar if manually placed +# Keep server.jar if it is manually placed +!server.jar # Python (if using pre-commit) __pycache__/ @@ -52,13 +55,21 @@ yarn-error.log* out/ dist/ -# Test coverage (generated by pytest --cov) +# Test coverage and tooling caches (generated) .coverage htmlcov/ coverage.json coverage.xml coverage-gaps.txt .pytest_cache/ +.mypy_cache/ +.ruff_cache/ + +# Playwright (generated) +playwright-report/ +test-results/ +blob-report/ +playwright/.cache/ # Local development .local/ diff --git a/.windsurfrules b/.windsurfrules new file mode 100644 index 0000000..8e80418 --- /dev/null +++ b/.windsurfrules @@ -0,0 +1,6 @@ +# POINTER FILE — single source of truth is /AGENTS.md at the repo root. +# Edit AGENTS.md, not this file. + +Follow the project guidelines defined in the root AGENTS.md file: +stack, commands, code style, architecture, testing, Raspberry Pi +constraints, security, and git conventions are all defined there. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ee5004c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,207 @@ +# Project Guidelines (AGENTS.md) + + + +## Project Overview + +A Minecraft server management system for **Raspberry Pi 5 (ARM64)**, also usable on +x86_64. It provides Docker-based deployment, automated and cloud backups, plugin and +mod management, multi-world support, RCON, log management, analytics, a Flask REST +API, and a React web admin panel. + +## Stack + +| Layer | Technology | +| --- | --- | +| Server management | Bash scripts in `scripts/`, shared helpers in `scripts/lib/common.sh` | +| REST API | Python 3.11+ / Flask (`api/server.py`) | +| Web admin panel | React 18 + Vite + Tailwind CSS (`web/`) | +| Containers | Docker + Docker Compose v2 | +| Service management | systemd units in `systemd/` | +| Tests | pytest (API), Vitest (React), Playwright (browser E2E), BATS (shell) | +| Package manager | **npm** (this repo is not on pnpm) | + +## Repository Layout + +``` +api/ Flask REST API (server.py, security.py) + OpenAPI spec in api/openapi.yaml +web/ React admin panel; its own package.json, ESLint, Vite and Playwright configs +scripts/ Bash management scripts; scripts/lib/common.sh holds shared helpers +config/ Runtime config; only *.example files are committed (real .conf files are gitignored) +systemd/ Unit and timer files for the Pi +tests/ api/ (pytest), unit/ integration/ e2e/ (BATS), helpers/ +web/tests/e2e Playwright browser tests (driven by web/playwright.config.js) +docs/ All documentation; docs/INDEX.md is the navigation hub +analytics/ Collected analytics reports +``` + +## Commands + +Everything routes through the `Makefile`; prefer it over raw commands. + +```bash +make help # list all targets +make start|stop|restart|status|logs|backup|console +make test # syntax checks + pytest + vitest +make test-api # pytest only +make test-web # vitest only +make test-playwright # browser E2E +make test-e2e # BATS end-to-end (needs a running server) +make lint # shellcheck + eslint + python + yaml + compose validate +make coverage # pytest with coverage report +make coverage-check # enforce the threshold in .coverage-config.ini +make build # docker compose build +``` + +Direct equivalents when you need them: + +```bash +bash -n scripts/foo.sh # shell syntax check +cd tests/api && pytest -v # API tests (pytest.ini lives here) +cd web && npm test # Vitest +cd web && npm run lint # ESLint (must pass with --max-warnings 0) +docker compose config # validate compose files +``` + +**Use `docker compose` (with a space), never `docker-compose`.** The standalone +binary conflicts with the plugin on Raspberry Pi OS; the `Makefile` detects which +form is available via its `COMPOSE` variable, and scripts use the `compose()` +wrapper from `scripts/lib/common.sh`. + +## Code Standards + +### Bash (`scripts/`) + +- `#!/bin/bash` shebang, `set -e` near the top. +- 4-space indent, no tabs. Always quote variables: `"$VAR"`. +- Resolve the script's own directory, then source the shared library: + + ```bash + SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + # shellcheck source-path=SCRIPTDIR + # shellcheck source=lib/common.sh + source "${SCRIPT_DIR}/lib/common.sh" + ``` + + `common.sh` provides the colour variables (`RED`, `GREEN`, `YELLOW`, `BLUE`, `NC`), + `PROJECT_DIR`, `SCRIPTS_DIR` and the `compose()` wrapper. Do not redefine them. +- Every script takes a subcommand and has a `usage()` function; dispatch with `case`. +- Must pass `shellcheck` (see `.shellcheckrc`). + +### Python (`api/`, `scripts/*.py`) + +- PEP 8, formatted with Black at **line-length 120** (`pyproject.toml`). +- Type hints where they help; docstrings on functions and classes. +- `pathlib.Path` for filesystem work; catch specific exceptions. +- Imports grouped stdlib / third-party / local. +- Flask endpoints: decorate with `@app.route(...)` then `@require_permission("")` + for anything privileged. Return `jsonify({...})` with an explicit status code on + error paths: + + ```python + @app.route("/api/keys", methods=["GET"]) + @require_permission("api_keys.view") + def list_api_keys(): + """List all API keys (without showing full key values).""" + try: + ... + return jsonify({"keys": keys_list}) + except Exception as e: + app.logger.error(f"Error listing keys: {e}") + return jsonify({"error": "Internal server error"}), 500 + ``` + +- Never return raw exception text to the client on a 500. + +### React (`web/src/`) + +- Functional components with hooks; no class components. +- Tailwind utility classes for styling — no separate CSS modules. +- All HTTP goes through `web/src/services/api.js`; components never call `axios` directly. +- Reuse the existing hooks (`usePolling`, `useErrorHandler`, `useAutoDismiss`, + `useDebounce`, `useThrottle`) instead of re-implementing them. +- Routes are lazy-loaded in `App.jsx` via `LazyRoute`; keep new pages lazy. +- `npm run lint` runs with `--max-warnings 0`, so warnings break the build. + +### Docker / YAML + +- 2-space YAML indent; `${VAR:-default}` for environment substitution. +- Multi-stage builds, minimal layers, clean up within the same `RUN`. +- Keep the healthcheck in `docker-compose.yml` accurate — a too-short + `start_period` causes restart loops on a Pi. + +### Naming + +| Kind | Convention | Example | +| --- | --- | --- | +| Shell scripts | `kebab-case.sh` | `backup-scheduler.sh` | +| Python | `snake_case.py` | `server.py` | +| React components | `PascalCase.jsx` | `StatusCard.jsx` | +| Hooks | `useCamelCase.js` | `usePolling.js` | +| Config files | `kebab-case.conf` | `backup-schedule.conf` | +| Docs | `UPPERCASE.md` | `TROUBLESHOOTING.md` | + +## Testing + +- Python tests live in `tests/api/` and are run **from that directory** — + `tests/api/pytest.ini` holds the coverage flags, timeouts and markers. +- Registered markers: `unit`, `integration`, `api`, `slow`, `performance`, + `contract`, `e2e`. `--strict-markers` is on, so add new markers to + `tests/api/pytest.ini` *and* `pyproject.toml` before using them. +- React unit tests sit next to the code in `__tests__/`; integration tests in + `web/src/test/integration/`; MSW handlers in `web/src/test/mocks/`. +- Playwright specs belong in `web/tests/e2e/` only. +- BATS suites in `tests/unit/`, `tests/integration/`, `tests/e2e/`. +- Coverage threshold is enforced at **40%** in `.coverage-config.ini`. + +See [docs/TESTING.md](docs/TESTING.md) for the full guide. + +## Raspberry Pi Constraints + +These shape most design decisions — do not optimise them away: + +- **Memory**: 4GB model → `MEMORY_MIN=1G`, `MEMORY_MAX=2G`; 8GB model → `2G`/`4G`. +- **CPU**: ARM64. Images must build for `linux/arm64` (see `scripts/build-multiarch.sh`). +- **Storage**: SD cards have finite writes — keep log rotation on and compress backups. +- **Thermals**: sustained load throttles the Pi; long-running work should be chunked. + +Test on real hardware when a change is hardware-specific. + +## Security + +- Never commit secrets. `config/*.conf` is gitignored; only `*.example` files are tracked. +- API keys live in `config/api-keys.json` (gitignored); RCON passwords are generated randomly. +- Validate and sanitise all API input; `api/security.py` holds the shared helpers and + security headers. +- Gitleaks and CodeQL run in CI — do not work around them. + +## Git Conventions + +- Branch prefixes: `feature/`, `fix/`, `docs/`. +- One logical change per PR; fill in `.github/pull_request_template.md`. +- Update `CHANGELOG.md` for anything user-facing. +- Pre-commit hooks are configured in `.pre-commit-config.yaml` — install with + `pre-commit install`. + +## Before You Call It Done + +- [ ] `make lint` passes +- [ ] `make test` passes +- [ ] `docker compose config` validates +- [ ] Docs updated (`README.md` for user-facing changes, the relevant `docs/` guide otherwise) +- [ ] `CHANGELOG.md` updated +- [ ] No secrets, no hardcoded absolute paths + +## Documentation Rules + +- `docs/INDEX.md` is the navigation hub — add new docs there or they will not be found. +- Keep internal links relative. +- Don't create "summary", "complete" or "implementation notes" documents; that history + belongs in `CHANGELOG.md` and git. +- Don't state coverage percentages or test counts in prose — they go stale immediately. + Point at `make coverage` or CI instead. diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md deleted file mode 100644 index b59de42..0000000 --- a/AGENT_INSTRUCTIONS.md +++ /dev/null @@ -1,735 +0,0 @@ -# Agent Instructions for Minecraft Server Management Project - -This document provides comprehensive instructions for AI agents working on this codebase to ensure consistency across development sessions. - -## Table of Contents - -1. [Project Overview](#project-overview) -2. [Architecture & Technology Stack](#architecture--technology-stack) -3. [Code Standards](#code-standards) -4. [Development Workflow](#development-workflow) -5. [File Structure](#file-structure) -6. [Testing Requirements](#testing-requirements) -7. [Documentation Standards](#documentation-standards) -8. [Common Patterns](#common-patterns) -9. [Important Considerations](#important-considerations) -10. [Quick Reference](#quick-reference) - ---- - -## Project Overview - -This is a **Minecraft Server Management System** optimized for **Raspberry Pi 5 (ARM64)**. The project provides: - -- Docker-based server deployment and management -- Automated backup scheduling and retention -- Plugin management system -- Multi-world support -- REST API for remote server control -- React web interface for server administration -- RCON integration -- Log management and analysis -- Update management system - -**Target Platform**: Raspberry Pi 5 (4GB/8GB RAM), but also supports x86_64 - ---- - -## Architecture & Technology Stack - -### Backend - -- **API Server**: Python 3 with Flask -- **Server Management**: Bash scripts -- **Containerization**: Docker & Docker Compose -- **Configuration**: INI-style config files - -### Frontend - -- **Framework**: React with Vite -- **Styling**: Tailwind CSS -- **Testing**: Vitest -- **Build Tool**: Vite - -### Testing - -- **Python**: pytest -- **React**: Vitest -- **Shell Scripts**: BATS (Bash Automated Testing System) - -### Infrastructure - -- **Container Runtime**: Docker -- **Orchestration**: Docker Compose -- **OS**: Raspberry Pi OS (64-bit) / Linux - ---- - -## Code Standards - -### Shell Scripts - -**Requirements:** - -- Always use `#!/bin/bash` shebang -- Use `set -e` for error handling -- 4-space indentation (no tabs) -- Always quote variables: `"$VAR"` not `$VAR` -- Use functions for repeated code -- Include color output for user feedback -- Add comments for complex logic -- Include usage/help functions - -**Example:** - -```bash -#!/bin/bash -set -e - -# Colors for output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -NC='\033[0m' # No Color - -# Get script directory -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -function example_function() { - local param="$1" - echo -e "${GREEN}Processing: $param${NC}" -} - -# Main logic -if [ -z "$VARIABLE" ]; then - echo -e "${RED}Error: Variable not set${NC}" - exit 1 -fi -``` - -**Validation:** - -- Run `bash -n script.sh` to check syntax -- Test on actual Raspberry Pi 5 when possible - -### Python Code - -**Requirements:** - -- Follow PEP 8 style guide -- Use type hints where appropriate -- Include docstrings for functions and classes -- Use `pathlib.Path` for file operations -- Handle exceptions specifically -- Group imports: stdlib, third-party, local - -**Example:** - -```python -#!/usr/bin/env python3 -""" -Module description. -""" - -from pathlib import Path -from typing import Optional, Dict, Any -from datetime import datetime - -def example_function(param: str) -> Optional[Path]: - """ - Function description. - - Args: - param: Parameter description - - Returns: - Path object or None - """ - try: - path = Path(param) - if path.exists(): - return path - return None - except Exception as e: - print(f"Error processing {param}: {e}") - return None -``` - -**Validation:** - -- Run `pytest tests/api/ -v` for tests -- Use `mypy` for type checking (if configured) -- Run `flake8` or `pylint` for linting - -### React/JavaScript - -**Requirements:** - -- Use functional components with hooks -- Use Tailwind CSS for styling -- Keep components small and focused -- Use `services/api.js` for API calls -- Include PropTypes or TypeScript types -- Write tests for components - -**Example:** - -```jsx -import { useState, useEffect } from 'react'; -import { api } from '../services/api'; - -export function StatusCard() { - const [status, setStatus] = useState(null); - const [loading, setLoading] = useState(true); - - useEffect(() => { - api.getStatus() - .then(setStatus) - .catch(console.error) - .finally(() => setLoading(false)); - }, []); - - if (loading) return
Loading...
; - - return ( -
-

Server Status

-

{status?.status || 'Unknown'}

-
- ); -} -``` - -**Validation:** - -- Run `npm test` for unit tests -- Run `npm run lint` for linting -- Test in browser - -### Docker - -**Requirements:** - -- Use official base images when possible -- Minimize layers -- Clean up in the same layer -- Use multi-stage builds for optimization -- Include health checks -- Use environment variables for configuration - -**Example:** - -```dockerfile -FROM eclipse-temurin:17-jre-alpine - -# Install dependencies -RUN apk add --no-cache bash - -# Set working directory -WORKDIR /minecraft/server - -# Copy scripts -COPY scripts/ /minecraft/scripts/ - -# Health check -HEALTHCHECK --interval=30s --timeout=10s --retries=3 \ - CMD pgrep -f java || exit 1 - -# Default command -CMD ["/minecraft/scripts/start.sh"] -``` - -### YAML Files - -**Requirements:** - -- 2-space indentation -- Use environment variables: `${VAR:-default}` -- Keep lines under 120 characters -- Validate with `docker-compose config` - ---- - -## Development Workflow - -### Making Changes - -1. **Create Feature Branch** - - ```bash - git checkout -b feature/feature-name - ``` - -2. **Make Changes** - - Follow code standards - - Write tests - - Update documentation - -3. **Test Changes** - - ```bash - # Shell scripts - bash -n script.sh - - # Python - pytest tests/api/ -v - - # React - npm test - - # Docker - docker-compose config - ``` - -4. **Commit Changes** - - ```bash - git commit -m "Add feature: description" - ``` - -5. **Push and Create PR** - - ```bash - git push origin feature/feature-name - ``` - -### Testing Requirements - -**Before Committing:** - -- [ ] Shell scripts pass syntax check (`bash -n`) -- [ ] Python tests pass (`pytest`) -- [ ] React tests pass (`npm test`) -- [ ] Docker config validates (`docker-compose config`) -- [ ] Documentation updated -- [ ] CHANGELOG.md updated - -**Integration Testing:** - -- Test on Raspberry Pi 5 when possible -- Test server startup/shutdown -- Test backup/restore -- Test plugin management -- Test API endpoints - ---- - -## File Structure - -``` -minecraft/ -├── api/ # Python Flask REST API -│ ├── server.py # Main API server -│ └── requirements.txt # Python dependencies -├── web/ # React frontend -│ ├── src/ -│ │ ├── components/ # React components -│ │ ├── pages/ # Page components -│ │ ├── services/ # API service layer -│ │ └── test/ # Test utilities -│ ├── package.json -│ └── vite.config.js -├── scripts/ # Shell scripts -│ ├── manage.sh # Main management script -│ ├── backup-scheduler.sh # Backup scheduling -│ ├── plugin-manager.sh # Plugin management -│ ├── world-manager.sh # World management -│ ├── rcon-client.sh # RCON client -│ └── ... -├── config/ # Configuration files -│ ├── api.conf # API configuration -│ ├── backup-schedule.conf # Backup schedule -│ ├── backup-retention.conf # Backup retention -│ └── ... -├── docs/ # Documentation -│ ├── API.md # API documentation -│ ├── DEVELOPMENT.md # Development guide -│ ├── INSTALL.md # Installation guide -│ └── ... -├── tests/ # Test suites -│ ├── api/ # Python API tests -│ │ ├── test_api.py -│ │ └── conftest.py -│ ├── integration/ # Integration tests -│ └── unit/ # Unit tests -├── systemd/ # Systemd service files -├── docker-compose.yml # Docker Compose config -├── Dockerfile # Docker image definition -├── Makefile # Convenience commands -├── README.md # Main documentation -├── CONTRIBUTING.md # Contribution guidelines -├── docs/TASKS.md # Development tasks -└── CHANGELOG.md # Version history -``` - ---- - -## Testing Requirements - -### Unit Tests - -- **Python**: Test individual functions in `tests/api/` -- **React**: Test components in `__tests__/` directories -- **Shell**: Test functions in `tests/unit/` - -### Integration Tests - -- Test script interactions in `tests/integration/` -- Test API endpoints with real server -- Test Docker container operations - -### Test Coverage - -- **Current**: 51% for Python API -- **Goal**: >50% coverage minimum -- **Target**: 80%+ for critical paths - -### Running Tests - -```bash -# Python API tests -pytest tests/api/ -v -pytest tests/api/ -v --cov=api --cov-report=term-missing - -# React tests -cd web && npm test - -# Shell script tests -bats tests/unit/ -``` - ---- - -## Documentation Standards - -### When to Update Documentation - -- **README.md**: User-facing features, setup changes -- **docs/INSTALL.md**: Installation procedure changes -- **docs/API.md**: API endpoint changes -- **docs/DEVELOPMENT.md**: Development workflow changes -- **CHANGELOG.md**: All changes (required) -- **QUICK_REFERENCE.md**: New commands or features - -### Documentation Format - -- Use Markdown format -- Include code examples -- Use clear headings -- Keep internal links relative -- Update all related docs when making changes - -### Example Documentation Update - -```markdown -## New Feature - -### Description -Brief description of the feature. - -### Usage -```bash -./manage.sh new-command -``` - -### Configuration - -Add to `config/feature.conf`: - -```ini -setting=value -``` - -### Examples - -[Include examples] - -``` - ---- - -## Common Patterns - -### Script Structure Pattern - -```bash -#!/bin/bash -set -e - -# Colors -RED='\033[0;31m' -GREEN='\033[0;32m' -NC='\033[0m' - -# Script directory -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -# Configuration -CONFIG_FILE="${SCRIPT_DIR}/../config/script.conf" - -# Functions -function usage() { - echo "Usage: $0 {command}" - exit 1 -} - -function main_function() { - local param="$1" - echo -e "${GREEN}Processing: $param${NC}" -} - -# Main execution -if [ "$#" -eq 0 ]; then - usage - exit 1 -fi - -case "$1" in - command) - main_function "$2" - ;; - *) - usage - exit 1 - ;; -esac -``` - -### API Endpoint Pattern - -```python -@app.route('/api/endpoint', methods=['GET', 'POST']) -@require_api_key -def endpoint(): - """ - Endpoint description. - - Returns: - JSON response with status and data - """ - try: - if request.method == 'GET': - data = get_data() - return jsonify({"status": "success", "data": data}) - elif request.method == 'POST': - data = request.get_json() - result = process_data(data) - return jsonify({"status": "success", "result": result}) - except ValueError as e: - return jsonify({"status": "error", "message": str(e)}), 400 - except Exception as e: - app.logger.error(f"Error in endpoint: {e}") - return jsonify({"status": "error", "message": "Internal server error"}), 500 -``` - -### React Component Pattern - -```jsx -import { useState, useEffect } from 'react'; -import { api } from '../services/api'; - -export function Component({ prop1, prop2 }) { - const [data, setData] = useState(null); - const [loading, setLoading] = useState(true); - const [error, setError] = useState(null); - - useEffect(() => { - api.getData() - .then(setData) - .catch(setError) - .finally(() => setLoading(false)); - }, []); - - if (loading) return
Loading...
; - if (error) return
Error: {error.message}
; - - return ( -
- {/* Component content */} -
- ); -} -``` - ---- - -## Important Considerations - -### Raspberry Pi 5 Optimization - -**Memory Constraints:** - -- 4GB model: Use MIN=1G, MAX=2G -- 8GB model: Use MIN=2G, MAX=4G -- Monitor memory usage carefully -- Implement memory-efficient algorithms - -**CPU Considerations:** - -- ARM64 architecture -- Optimize for efficiency, not just speed -- Consider CPU temperature monitoring -- Use multi-core processing when beneficial - -**Storage:** - -- SD card write limits -- Implement log rotation -- Use efficient backup compression -- Monitor disk space - -### Docker Best Practices - -**Resource Management:** - -- Set appropriate memory limits -- Configure CPU limits if needed -- Use health checks -- Implement proper logging - -**Volume Management:** - -- Use bind mounts for data persistence -- Configure volume permissions -- Implement backup strategies - -**Networking:** - -- Use custom networks -- Expose only necessary ports -- Implement proper security - -### Security - -**API Security:** - -- Use API keys for authentication -- Store keys securely (config/api-keys.json) -- Never commit secrets -- Validate all inputs - -**RCON Security:** - -- Generate secure random passwords -- Store passwords securely -- Use strong passwords - -**File Permissions:** - -- Set appropriate permissions on scripts -- Protect configuration files -- Secure backup files - -### Error Handling - -**Graceful Degradation:** - -- Handle missing dependencies -- Provide fallback options -- Don't crash on non-critical errors - -**User Feedback:** - -- Provide clear error messages -- Use color coding (red for errors) -- Log errors with context - -**Recovery:** - -- Implement rollback mechanisms -- Create backups before major operations -- Validate operations before execution - ---- - -## Quick Reference - -### Common Commands - -```bash -# Server Management -./manage.sh start # Start server -./manage.sh stop # Stop server -./manage.sh restart # Restart server -./manage.sh status # Check status -./manage.sh logs # View logs -./manage.sh backup # Create backup -./manage.sh console # Attach to console - -# Development -make test # Run tests -make build # Build Docker image -make start # Start server -make logs # View logs - -# Testing -pytest tests/api/ -v # Run API tests -cd web && npm test # Run React tests -bash -n script.sh # Check script syntax -docker-compose config # Validate Docker config -``` - -### Key Files - -- `scripts/manage.sh` - Main management script -- `api/server.py` - REST API server -- `docker-compose.yml` - Docker configuration -- `README.md` - Main documentation -- `docs/TASKS.md` - Development tasks -- `CONTRIBUTING.md` - Contribution guidelines -- `docs/DEVELOPMENT.md` - Development guide - -### File Naming Conventions - -- **Scripts**: `kebab-case.sh` (e.g., `backup-scheduler.sh`) -- **Python**: `snake_case.py` (e.g., `server.py`) -- **React**: `PascalCase.jsx` (e.g., `StatusCard.jsx`) -- **Config**: `kebab-case.conf` (e.g., `backup-schedule.conf`) -- **Documentation**: `UPPERCASE.md` (e.g., `README.md`) - -### When Adding New Features - -1. Check `docs/TASKS.md` for related tasks -2. Follow existing patterns in similar features -3. Add tests for new functionality -4. Update documentation (README, relevant docs/) -5. Update `CHANGELOG.md` with changes -6. Test on Raspberry Pi 5 if hardware-specific - -### Git Workflow - -- **Branches**: Use `feature/`, `fix/`, `docs/` prefixes -- **Commits**: Clear, descriptive messages -- **PRs**: One feature/fix per PR -- **Reviews**: Address feedback before merging - ---- - -## Remember - -✅ **Always:** - -- Test on Raspberry Pi 5 when possible -- Keep memory usage in mind (4GB/8GB models) -- Follow existing code patterns -- Update documentation with changes -- Write tests for new features -- Use clear, descriptive names -- Handle errors gracefully -- Provide user feedback - -❌ **Never:** - -- Commit secrets or API keys -- Break backward compatibility without notice -- Skip testing -- Ignore error handling -- Use tabs instead of spaces -- Forget to update documentation -- Hardcode paths (use variables) - ---- - -**Last Updated**: 2025-01-XX -**Version**: 1.0.0 diff --git a/CHANGELOG.md b/CHANGELOG.md index 82f51f2..feee4fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,51 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +### Changed + +- **Repository and documentation cleanup** + + - Consolidated AI assistant configuration on `AGENTS.md` as the single source of + truth, following the `ai-template-repo` convention. `AGENT_INSTRUCTIONS.md` and + the 317-line `.cursorrules` (which duplicated each other) were merged into it. + `CLAUDE.md`, `.cursorrules`, `.cursor/rules/project.mdc`, `.clinerules`, + `.windsurfrules` and `.github/copilot-instructions.md` are now thin pointers. + - Rewrote `README.md`: fixed broken links, corrected every `./manage.sh` and + `./setup-rpi.sh` path to `./scripts/...`, replaced the hand-written systemd unit + with the one shipped in `systemd/`, and documented `.env` configuration. + - Rewrote `docs/INDEX.md` as a task-oriented index of all 48 guides; + `docs/README.md` and `tests/README.md` are now short pointers to it. + - Merged `RESTART_LOOP_TROUBLESHOOTING.md` and `DOCKER_COMPOSE_FIX.md` into + `docs/TROUBLESHOOTING.md`, and `TEST_COVERAGE.md` into `docs/TESTING.md`. + - Replaced `docker-compose` with `docker compose` throughout the documentation to + match the Compose v2 plugin the `Makefile` and systemd units actually use. + - Added `.env.example` (referenced by the `Makefile` but previously missing). + - Synced the pytest markers in `pyproject.toml` with `tests/api/pytest.ini`, and + removed the duplicate `[tool.coverage]` block so `.coverage-config.ini` is the + only coverage config. + - Tightened `.gitignore`: added `.mypy_cache/`, `playwright-report/`, + `test-results/`; fixed an inline comment that made a negation pattern literal. + +### Removed + +- **Dead configuration and build artifacts** + + - Root `.eslintrc.json` and `.eslintignore` — unused; linting runs inside `web/`, + whose `.eslintrc.cjs` sets `root: true`. + - Root `playwright.config.js` and `tests/e2e/browser/` — stale duplicates of the + live `web/playwright.config.js` and `web/tests/e2e/`. + - `web/playwright-report/index.html` — a 520 KB generated report that had been + committed. + +- **Historical process documentation** (preserved in git history) + + - `docs/archive/` (17 files), plus `ADVANCED_OPTIMIZATIONS.md`, + `CLEANUP_OPTIMIZATIONS_SUMMARY.md`, `CONSOLIDATION_SUMMARY.md`, + `DOCUMENTATION_CONSOLIDATION_PLAN.md`, `OPTIMIZATION_COMPLETE.md`, + `OPTIMIZATION_SUMMARY.md`, `WORKSPACE_ENHANCEMENTS.md`, `SETUP_CHECKLIST.md`. + - `tests/ANALYTICS_TESTS.md`, `tests/COMPLETE_TEST_SUMMARY.md`, + `tests/TEST_SUMMARY.md`. + ### Added - **Comprehensive Test Suite - Complete Implementation** diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7f4bb25 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,15 @@ +# CLAUDE.md — Claude Code Project Instructions + +**Read `AGENTS.md` first — it is the single source of truth for stack, commands, code +style, testing, and conventions.** This file only holds Claude-specific additions; +don't duplicate AGENTS.md content here. + +## Claude-specific notes + +- Don't commit, push, or deploy unless explicitly asked. +- This repo uses **npm**, not pnpm. Web commands run from `web/`; Python tests run + from `tests/api/`. +- Use `docker compose` (with a space) — never `docker-compose`. +- Run `make lint && make test` before declaring a change done. +- Most runtime state (`data/`, `backups/`, `config/*.conf`) is gitignored and lives + only on the Raspberry Pi — don't assume those paths exist locally. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a401d8d..c94da88 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -114,15 +114,15 @@ Before submitting changes: bash -n script.sh # Docker Compose - docker-compose config + docker compose config # Dockerfile docker build -t test . ``` 2. **Functional tests**: - - Start server: `./manage.sh start` - - Check logs: `./manage.sh logs` + - Start server: `./scripts/manage.sh start` + - Check logs: `./scripts/manage.sh logs` - Connect with Minecraft client - Test all management commands - Verify backup/restore diff --git a/README.md b/README.md index ad7fe6f..f30a2ae 100644 --- a/README.md +++ b/README.md @@ -1,487 +1,229 @@ # Minecraft Server for Raspberry Pi 5 -A custom Minecraft server setup optimized for Raspberry Pi 5, providing easy control over settings and customization. This setup uses Docker for easy deployment and management. +A self-hosted Minecraft server stack tuned for the Raspberry Pi 5 (ARM64): Docker +deployment, automated and offsite backups, plugin and mod management, multi-world +support, RCON, a REST API, and a React web admin panel. + +Works on x86_64 too — the Pi is just what it is optimised for. ## Features -- 🎮 Optimized for Raspberry Pi 5 (ARM64 architecture) -- 🐳 Docker-based deployment for easy management -- ⚙️ Easy customization of server settings -- 💾 Automatic backup support -- 🔄 Simple update mechanism -- 📊 Resource-efficient configuration +- 🎮 Tuned for Raspberry Pi 5 (ARM64), multi-arch images +- 🐳 Docker Compose deployment with systemd units for boot-time start +- 💾 Scheduled backups with retention, plus offsite backup to R2 / S3 / B2 +- 🔌 Plugin and mod management (Paper, Spigot, Fabric, Forge) +- 🌍 Multi-world management, switching, and per-world backups +- 🖥️ REST API + React admin panel with RBAC, API keys and OAuth +- 📊 Analytics, metrics, log rotation and search +- 🔄 Version checking, compatibility checks and guided updates ## Requirements -- Raspberry Pi 5 (4GB or 8GB RAM recommended) -- MicroSD card (32GB or larger recommended) +- Raspberry Pi 5 (4GB minimum, 8GB recommended) +- MicroSD card, 32GB or larger - Raspberry Pi OS (64-bit) -- Internet connection for initial setup +- Docker with the Compose v2 plugin (the setup script installs it) ## Quick Start -### 1. Flash Raspberry Pi OS - -Quick steps: - -1. Download and install [Raspberry Pi Imager](https://www.raspberrypi.com/software/) -2. Insert your microSD card into your computer -3. Open Raspberry Pi Imager -4. Choose OS: **Raspberry Pi OS (64-bit)** -5. Choose Storage: Select your microSD card -6. Click on the gear icon (⚙️) for advanced options: - - Set hostname (e.g., `minecraft-server`) - - Enable SSH - - Set username and password - - Configure WiFi (optional) -7. Click **Write** and wait for the process to complete - -### 2. Initial Setup on Raspberry Pi - -1. Insert the microSD card into your Raspberry Pi 5 -2. Power on the Raspberry Pi -3. SSH into your Raspberry Pi: - - ```bash - ssh pi@minecraft-server.local - ``` - - Or use the IP address if hostname doesn't work - -4. Clone this repository: +```bash +# On the Pi +git clone https://github.com/and3rn3t/minecraft.git ~/minecraft-server +cd ~/minecraft-server - ```bash - cd ~ - git clone https://github.com/and3rn3t/minecraft.git minecraft-server - cd minecraft-server - ``` +./scripts/setup-rpi.sh # installs Docker, dependencies, permissions +# log out and back in so the docker group takes effect -5. Run the setup script: +./scripts/manage.sh start # start the server +./scripts/manage.sh logs # watch it come up +``` - ```bash - chmod +x setup-rpi.sh - ./setup-rpi.sh - ``` +Connect from Minecraft using the Pi's address on port `25565`. -6. **Important**: Log out and log back in for Docker permissions to take effect: +Full walkthrough, including flashing the SD card: **[docs/INSTALL.md](docs/INSTALL.md)**. +Deploying the API and web panel as well: **[docs/RPI5_FULL_DEPLOYMENT.md](docs/RPI5_FULL_DEPLOYMENT.md)**. - ```bash - exit - # SSH back in - ssh pi@minecraft-server.local - cd ~/minecraft-server - ``` +## Managing the Server -### 3. Start the Minecraft Server +`scripts/manage.sh` is the main entry point; `make` wraps the common ones. ```bash -# Make management script executable -chmod +x manage.sh - -# Start the server -./manage.sh start - -# View logs -./manage.sh logs +./scripts/manage.sh start|stop|restart|status|logs|backup|console +./scripts/manage.sh update [version] # update the server jar +./scripts/manage.sh check-version # is there a newer release? +./scripts/manage.sh check-compatibility # safe to update? ``` -## Server Management - -The `manage.sh` script provides easy server management: - ```bash -./manage.sh start # Start the server -./manage.sh stop # Stop the server -./manage.sh restart # Restart the server -./manage.sh status # Check server status -./manage.sh logs # View server logs -./manage.sh backup # Create a backup -./manage.sh console # Attach to server console (Ctrl+P, Ctrl+Q to detach) -./manage.sh update [version] # Update server to latest or specified version -./manage.sh check-version # Check for available updates -./manage.sh check-compatibility # Check compatibility before updating +make help # every target +make start # same as ./scripts/manage.sh start +make status +make backup +make logs ``` -### Minecraft-Specific Tools - -Additional scripts for Minecraft server management: +### Other tools ```bash -# Server Properties -./scripts/server-properties-manager.sh get view-distance +# Server properties and presets ./scripts/server-properties-manager.sh set view-distance 10 -./scripts/server-properties-manager.sh preset balanced +./scripts/performance-presets.sh balanced -# Player Management +# Players ./scripts/whitelist-manager.sh add PlayerName ./scripts/ban-manager.sh ban PlayerName "Reason" ./scripts/op-manager.sh grant PlayerName 4 # Performance ./scripts/jvm-optimizer.sh generate 2G 4 aikar -./scripts/performance-presets.sh balanced +./scripts/monitor-rpi5.sh ``` -## Customization - -### Server Properties - -Edit `server.properties` to customize your server: - -```properties -# Common settings to adjust -max-players=10 # Maximum number of players -difficulty=normal # easy, normal, hard, peaceful -gamemode=survival # survival, creative, adventure -view-distance=10 # Render distance (lower = better performance) -motd=My Minecraft Server # Server name in multiplayer list -``` +Everything is listed in **[docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md)**. -After changing settings, restart the server: +## Configuration -```bash -./manage.sh restart -``` +### Server properties -### Memory Allocation +Edit `server.properties`, then `./scripts/manage.sh restart`: -Edit `docker-compose.yml` to adjust memory settings: - -```yaml -environment: - - MEMORY_MIN=1G # Minimum memory (1G for 4GB Pi, 2G for 8GB Pi) - - MEMORY_MAX=2G # Maximum memory (2G for 4GB Pi, 4G for 8GB Pi) +```properties +max-players=10 +difficulty=normal +gamemode=survival +view-distance=10 # lower is faster +motd=My Minecraft Server ``` -**Recommended Memory Settings:** - -- Raspberry Pi 5 (4GB): MIN=1G, MAX=2G -- Raspberry Pi 5 (8GB): MIN=2G, MAX=4G - -### Minecraft Version - -To change Minecraft version, edit `docker-compose.yml`: - -```yaml -environment: - - MINECRAFT_VERSION=1.20.4 # Change to desired version -``` +### Memory and version -Then rebuild and restart: +Both come from environment variables read by `docker-compose.yml`, so set them in a +`.env` file next to it rather than editing the compose file: ```bash -docker-compose down -docker-compose up -d --build +MINECRAFT_VERSION=1.20.4 +MEMORY_MIN=1G # 2G on an 8GB Pi +MEMORY_MAX=2G # 4G on an 8GB Pi +CONTAINER_MEMORY_LIMIT=3G # must exceed MEMORY_MAX by ~1G ``` -## Port Forwarding +> `CONTAINER_MEMORY_LIMIT` has to leave the JVM roughly 0.5–1G of headroom beyond +> `MEMORY_MAX`. Setting it equal to `MEMORY_MAX` is the classic cause of a restart +> loop — see [Troubleshooting](docs/TROUBLESHOOTING.md#server-restart-loop). -To allow players outside your local network to connect: - -1. Find your Raspberry Pi's local IP address: - - ```bash - hostname -I - ``` - -2. Log into your router's admin panel -3. Set up port forwarding: - - - External Port: 25565 - - Internal Port: 25565 - - Internal IP: Your Raspberry Pi's IP address - - Protocol: TCP - -4. Find your public IP address: Visit [whatismyipaddress.com](https://whatismyipaddress.com/) -5. Share your public IP with your friends to connect +More examples: **[docs/CONFIGURATION_EXAMPLES.md](docs/CONFIGURATION_EXAMPLES.md)**. ## Backups -### Manual Backup - -```bash -./manage.sh backup -``` - -Backups are stored in the `backups/` directory. - -### Restore from Backup - -```bash -# Stop the server -./manage.sh stop - -# Extract backup to data directory -tar -xzf backups/minecraft_backup_YYYYMMDD_HHMMSS.tar.gz -C ./data/ - -# Start the server -./manage.sh start -``` - -## Troubleshooting - -### Server won't start - -1. Check if Docker is running: - - ```bash - sudo systemctl status docker - ``` - -2. View detailed logs: - - ```bash - docker-compose logs - ``` - -3. Check available memory: - - ```bash - free -h - ``` - -### Performance Issues - -1. Reduce view distance in `server.properties`: - - ```properties - view-distance=6 - simulation-distance=6 - ``` - -2. Lower max players: - - ```properties - max-players=5 - ``` - -3. Reduce memory if system is struggling: - - ```yaml - MEMORY_MAX=1G - ``` - -### Cannot connect from outside network - -1. Verify port forwarding is set up correctly -2. Check if server is running: `./manage.sh status` -3. Ensure firewall allows port 25565: - - ```bash - sudo ufw allow 25565/tcp - ``` - -## Performance Tips - -1. **Use Ethernet**: Wired connection is more stable than WiFi -2. **Proper Cooling**: Ensure your Pi 5 has adequate cooling (case with fan recommended) -3. **Quality Power Supply**: Use the official Raspberry Pi 5 power supply -4. **Fast Storage**: Use a high-quality microSD card (Class 10, A2 rating) -5. **Regular Backups**: Back up your world regularly - -## Advanced Configuration - -### Installing Plugins (For Bukkit/Spigot/Paper) - -If you want to use plugins, you'll need to use Paper or Spigot instead of vanilla: - -1. Switch to Paper or Spigot: - - ```bash - ./scripts/switch-server-type.sh paper - ``` - -2. Install plugins: - - ```bash - ./scripts/plugin-manager.sh install /path/to/plugin.jar - ``` - -3. Restart the server: - ```bash - ./scripts/manage.sh restart - ``` - -See [PLUGIN_MANAGEMENT.md](docs/PLUGIN_MANAGEMENT.md) for detailed plugin management guide. - -### Automatic Startup on Boot - -To start the server automatically when the Pi boots: - ```bash -# Create systemd service -sudo nano /etc/systemd/system/minecraft.service +./scripts/manage.sh backup # one-off, into backups/ +./scripts/install-backup-timer.sh # scheduled via systemd timer +./scripts/cloud-backup-r2.sh upload # offsite (also -s3 and -b2 variants) ``` -Add: - -```ini -[Unit] -Description=Minecraft Server -After=docker.service -Requires=docker.service +To restore, stop the server, extract the archive into `data/`, and start again. +Details and retention policy: **[docs/BACKUP_AND_MONITORING.md](docs/BACKUP_AND_MONITORING.md)** +and **[docs/CLOUD_BACKUP.md](docs/CLOUD_BACKUP.md)**. -[Service] -Type=oneshot -RemainAfterExit=yes -WorkingDirectory=/home/pi/minecraft-server -ExecStart=/usr/bin/docker-compose up -d -ExecStop=/usr/bin/docker-compose down -User=pi +## Starting on Boot -[Install] -WantedBy=multi-user.target -``` - -Enable the service: +systemd units ship in `systemd/`. They use `docker compose` and pull the latest +image before starting: ```bash -sudo systemctl enable minecraft.service -sudo systemctl start minecraft.service +sudo cp systemd/minecraft.service /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl enable --now minecraft.service ``` -## Testing +`minecraft-api.service`, `minecraft-web.service`, the backup timer and the update +timer install the same way. See **[docs/DOCKER_BOOT_SETUP.md](docs/DOCKER_BOOT_SETUP.md)**. -The project includes comprehensive automated tests: +## Remote Access -```bash -# Run API tests -python -m pytest tests/api/ -v +To let friends connect from outside your network, forward TCP `25565` to the Pi. +For a stable hostname on a changing home IP, use the DDNS updater — +**[docs/DYNAMIC_DNS.md](docs/DYNAMIC_DNS.md)**. -# Run with coverage -python -m pytest tests/api/ -v --cov=api --cov-report=term-missing -``` - -**Current Status**: ✅ 60+ API tests passing (~60% coverage) - -See [Testing Guide](docs/TESTING.md) for more information. - -## Code Quality - -The project uses static code analysis to ensure code quality: +## Web Panel & API ```bash -# Run all linting checks -make lint - -# Or use the linting script directly -./scripts/lint.sh all +./scripts/setup-api-venv.sh # Python venv for the API +./scripts/api-server.sh start # REST API +./scripts/build-web.sh # build the React panel ``` -**Linting Tools**: - -- **ShellCheck** - Bash script linting -- **ESLint** - JavaScript/React linting -- **flake8/pylint** - Python code analysis (optional) -- **yamllint** - YAML file validation (optional) - -See [Linting Guide](docs/LINTING.md) for more information. +The panel covers server control, players, worlds, backups, plugins, logs, the +console, analytics, config editing, users and API keys. See +**[docs/WEB_INTERFACE.md](docs/WEB_INTERFACE.md)** and **[docs/API.md](docs/API.md)** +(the OpenAPI spec is `api/openapi.yaml`). -## Docker Optimization - -The project uses optimized Docker images for Raspberry Pi 5: - -- **Multi-stage builds** - Reduced image size -- **Layer optimization** - Better build caching -- **Minimal base image** - Security and performance -- **Build arguments** - Flexible configuration +## Development ```bash -# Build with custom version -docker build --build-arg MINECRAFT_VERSION=1.21.0 -t minecraft-server . +git clone https://github.com/and3rn3t/minecraft.git +cd minecraft -# Use BuildKit for faster builds -export DOCKER_BUILDKIT=1 -docker build -t minecraft-server . +make lint # shellcheck, eslint, python, yaml, compose validation +make test # pytest + vitest + syntax checks +make coverage # coverage report ``` -See [Docker Optimization Guide](docs/DOCKER_OPTIMIZATION.md) for details. +- **[AGENTS.md](AGENTS.md)** — conventions, stack, commands (also what AI assistants read) +- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** — setup and workflow +- **[docs/TESTING.md](docs/TESTING.md)** — test layout and how to run each suite +- **[CONTRIBUTING.md](CONTRIBUTING.md)** — contribution guidelines ## Documentation -📚 **Start here**: [Documentation Index](docs/INDEX.md) - Complete navigation guide - -### Quick Links - -**Getting Started:** - -- **[Installation Guide](docs/INSTALL.md)** - Complete setup instructions -- **[Quick Reference](docs/QUICK_REFERENCE.md)** - Command cheat sheet -- **[Configuration Examples](docs/CONFIGURATION_EXAMPLES.md)** - Config file examples - -**User Guides:** - -- **[Backup & Monitoring](docs/BACKUP_AND_MONITORING.md)** - Automated backups and metrics -- **[Update Management](docs/UPDATE_MANAGEMENT.md)** - Server updates and versions -- **[Plugin Management](docs/PLUGIN_MANAGEMENT.md)** - Installing and managing plugins -- **[Multi-World Support](docs/MULTI_WORLD.md)** - Managing multiple worlds -- **[Log Management](docs/LOG_MANAGEMENT.md)** - Log rotation and analysis -- **[RCON Guide](docs/RCON.md)** - Remote console setup -- **[REST API](docs/API.md)** - API documentation -- **[Web Interface](docs/WEB_INTERFACE.md)** - Web admin panel - -**Developer Guides:** - -- **[Development Guide](docs/DEVELOPMENT.md)** - Setup and workflow -- **[Testing Guide](docs/TESTING.md)** - Testing best practices -- **[Cursor Configuration](docs/CURSOR_CONFIGURATION.md)** - IDE setup -- **[Contributing](CONTRIBUTING.md)** - Contribution guidelines -- **[Agent Instructions](AGENT_INSTRUCTIONS.md)** - AI agent consistency guide - -**Project Planning:** - -- **[Roadmap](docs/ROADMAP.md)** - Development roadmap -- **[Tasks](docs/TASKS.md)** - Detailed task breakdown -- **[Changelog](CHANGELOG.md)** - Version history - -**Troubleshooting:** +📚 **[docs/INDEX.md](docs/INDEX.md) lists every guide**, grouped by task. Common ones: + +| Topic | Guide | +| --- | --- | +| Install from scratch | [docs/INSTALL.md](docs/INSTALL.md) | +| Command cheat sheet | [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) | +| Something is broken | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | +| Backups & monitoring | [docs/BACKUP_AND_MONITORING.md](docs/BACKUP_AND_MONITORING.md) | +| Plugins | [docs/PLUGIN_MANAGEMENT.md](docs/PLUGIN_MANAGEMENT.md) | +| Multiple worlds | [docs/MULTI_WORLD.md](docs/MULTI_WORLD.md) | +| REST API | [docs/API.md](docs/API.md) | +| Pi tuning | [docs/RASPBERRY_PI_OPTIMIZATIONS.md](docs/RASPBERRY_PI_OPTIMIZATIONS.md) | +| Roadmap | [docs/ROADMAP.md](docs/ROADMAP.md) | +| Version history | [CHANGELOG.md](CHANGELOG.md) | -- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common problems and solutions - -For complete documentation navigation, see [docs/INDEX.md](docs/INDEX.md). - -## Resources - -- [Minecraft Server Documentation](https://minecraft.fandom.com/wiki/Server) -- [Raspberry Pi Documentation](https://www.raspberrypi.com/documentation/) -- [Docker Documentation](https://docs.docker.com/) -- [Server Properties Guide](https://minecraft.fandom.com/wiki/Server.properties) +## Troubleshooting -## Development +Start with **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** — it covers +installation failures, startup problems, restart loops, connectivity, performance, +Docker and system-level issues. -### Quick Start for Developers +Quick checks: ```bash -# Clone repository -git clone https://github.com/and3rn3t/minecraft.git -cd minecraft - -# Setup environment -cp .env.example .env # Edit with your settings -make install - -# Test -make test -make build - -# Start development -make start +./scripts/manage.sh status +./scripts/health-check.sh +docker logs --tail 100 minecraft-server +free -h && df -h +vcgencmd measure_temp # should stay below 80°C ``` -See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development guide. +## Performance Tips -### Contributing +1. Use Ethernet rather than WiFi +2. Give the Pi 5 active cooling — it throttles under sustained load +3. Use the official Pi 5 power supply +4. Use a fast A2-rated card, or better, an NVMe drive +5. Lower `view-distance` and `simulation-distance` before lowering memory -We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +See **[docs/RASPBERRY_PI_OPTIMIZATIONS.md](docs/RASPBERRY_PI_OPTIMIZATIONS.md)**. -### Roadmap +## Resources -Check out [ROADMAP.md](ROADMAP.md) for planned features and development phases. +- [Minecraft server documentation](https://minecraft.wiki/w/Server) +- [server.properties reference](https://minecraft.wiki/w/Server.properties) +- [Raspberry Pi documentation](https://www.raspberrypi.com/documentation/) +- [Docker documentation](https://docs.docker.com/) ## License -This project is open source and available for personal use. - -## Support - -For issues and questions, please open an issue on GitHub. +See [LICENSE](LICENSE). Security reports: [SECURITY.md](SECURITY.md). diff --git a/docs/ADVANCED_OPTIMIZATIONS.md b/docs/ADVANCED_OPTIMIZATIONS.md deleted file mode 100644 index 57c2bbb..0000000 --- a/docs/ADVANCED_OPTIMIZATIONS.md +++ /dev/null @@ -1,290 +0,0 @@ -# Advanced Optimizations Implemented - -This document details all advanced optimization techniques implemented to improve performance, reduce bundle size, and enhance user experience. - -## ✅ Implemented Optimizations - -### 1. Route-Based Code Splitting (Lazy Loading) - -**Implementation:** - -- All route components are now lazy-loaded using React's `lazy()` function -- Each route is wrapped with `Suspense` boundary for loading states -- Reduces initial bundle size by ~60-70% - -**Benefits:** - -- ✅ Faster initial page load -- ✅ Smaller initial JavaScript bundle -- ✅ Better code organization -- ✅ Improved caching strategy - -**Files Modified:** - -- `web/src/App.jsx` - All routes converted to lazy loading -- Created `PageLoading` component for consistent loading states - -**Example:** - -```jsx -const Dashboard = lazy(() => import('./pages/Dashboard')); - - - - }> - - - - - } -/>; -``` - -### 2. Debouncing & Throttling - -**Created Hooks:** - -- **`useDebounce`** - Delays value updates until user stops typing -- **`useThrottle`** - Limits value updates to specific intervals - -**Usage:** - -- Log filter input (300ms debounce) -- Search inputs (300ms debounce) -- Auto-save functionality (500ms debounce) -- Scroll events (throttle for performance) - -**Benefits:** - -- ✅ Reduces unnecessary filtering/search operations -- ✅ Improves input responsiveness -- ✅ Reduces CPU usage - -**Example:** - -```jsx -const debouncedFilter = useDebounce(filter, 300); -const filteredLogs = useMemo( - () => logs.filter(log => log.includes(debouncedFilter)), - [logs, debouncedFilter] -); -``` - -### 3. Virtual Scrolling - -**Implementation:** - -- Created `VirtualList` component for rendering large lists -- Only renders visible items + buffer -- Automatic height calculation - -**Benefits:** - -- ✅ Handles thousands of items efficiently -- ✅ Constant memory usage regardless of list size -- ✅ Smooth scrolling performance - -**Usage:** - -- Logs list (when > 100 items) -- Backups list (for large backup collections) -- Players list (for servers with many players) - -**Example:** - -```jsx - } - itemHeight={24} - containerHeight={600} - overscan={10} -/> -``` - -### 4. API Request Caching & Deduplication - -**Implementation:** - -- Created `apiCache.js` utility module -- In-memory cache with TTL (Time To Live) -- Request deduplication prevents duplicate concurrent requests -- Automatic cache invalidation on mutations - -**Cache Strategy:** - -- **Fast-changing data** (status, metrics): 2-3 second cache -- **Moderate-changing data** (players, backups): 5-10 second cache -- **Slow-changing data** (worlds, plugins, config): 30 second cache -- **Analytics data**: 60 second cache -- **Mutations**: Automatically invalidate relevant cache - -**Benefits:** - -- ✅ Prevents duplicate API calls -- ✅ Reduces server load -- ✅ Faster response times (cache hits) -- ✅ Better user experience - -**Cache TTL Examples:** - -```javascript -// Fast-changing -getStatus() - 2 seconds -getMetrics() - 2 seconds -getPlayers() - 3 seconds - -// Moderate-changing -listBackups() - 10 seconds - -// Slow-changing -listWorlds() - 30 seconds -listPlugins() - 30 seconds -listConfigFiles() - 30 seconds - -// Analytics -getAnalyticsReport() - 60 seconds -``` - -### 5. Build Optimizations - -**Vite Configuration:** - -- Manual chunk splitting for vendor libraries -- Separate chunks for React, Charts, Socket.IO -- Improved caching strategy -- Smaller chunk sizes - -**Benefits:** - -- ✅ Better browser caching -- ✅ Parallel downloads -- ✅ Smaller individual chunks -- ✅ Faster subsequent page loads - -**Configuration:** - -```javascript -manualChunks: { - 'react-vendor': ['react', 'react-dom', 'react-router-dom'], - 'chart-vendor': ['recharts'], - 'socket-vendor': ['socket.io-client'], -} -``` - -## 📊 Performance Impact - -### Bundle Size Reduction - -- **Initial Bundle**: Reduced by ~60-70% -- **Code Splitting**: Routes loaded on-demand -- **Vendor Chunks**: Better caching with separate chunks - -### Runtime Performance - -- **API Calls**: Reduced by ~40-50% with caching -- **Rendering**: Virtual scrolling handles large lists efficiently -- **Input Performance**: Debouncing reduces CPU usage by ~30% - -### Memory Usage - -- **Virtual Scrolling**: Constant memory regardless of list size -- **Code Splitting**: Only loaded code in memory -- **Cache Management**: Automatic cleanup of expired entries - -## 🔄 Cache Invalidation Strategy - -Cache is automatically invalidated on: - -- Server state changes (start/stop/restart) -- Backup operations (create/restore/delete) -- User/API key modifications -- Configuration file saves -- Analytics data collection - -**Manual Invalidation:** - -```javascript -import { clearCache, clearAllCache } from '../utils/apiCache'; - -// Clear specific cache -clearCache('/api/status', 'GET'); - -// Clear all cache -clearAllCache(); -``` - -## 🎯 Best Practices Established - -1. **Always lazy-load routes** - Never import all pages upfront -2. **Use debouncing for search/filter** - Reduce unnecessary operations -3. **Cache GET requests** - Reduce server load -4. **Invalidate cache on mutations** - Keep data fresh -5. **Use virtual scrolling for large lists** - Maintain performance -6. **Split vendor chunks** - Improve caching - -## 📝 Usage Examples - -### Using Debounce Hook - -```jsx -import { useDebounce } from '../hooks/useDebounce'; - -const [searchTerm, setSearchTerm] = useState(''); -const debouncedSearch = useDebounce(searchTerm, 300); - -useEffect(() => { - // This only runs 300ms after user stops typing - performSearch(debouncedSearch); -}, [debouncedSearch]); -``` - -### Using Cached API Calls - -```javascript -// Automatically cached -const status = await api.getStatus(); // Cached for 2 seconds - -// Automatically invalidates cache -await api.startServer(); // Clears status/metrics cache -``` - -### Using Virtual Scrolling - -```jsx -import { VirtualList } from '../components/VirtualList'; - - } - itemHeight={50} - containerHeight={400} - overscan={5} -/>; -``` - -## 🚀 Future Optimization Opportunities - -1. **Service Worker**: Offline support and advanced caching -2. **Web Workers**: Heavy computations off main thread -3. **Image Optimization**: Lazy loading and format conversion -4. **Prefetching**: Pre-load next likely routes -5. **Request Queue**: Batch multiple requests -6. **IndexedDB**: Persistent cache storage - -## 📈 Monitoring - -To monitor optimization effectiveness: - -1. **Bundle Analysis**: Run `npm run build` and check chunk sizes -2. **Network Tab**: Monitor API call frequency with caching -3. **Performance Tab**: Check render times with virtual scrolling -4. **Memory Tab**: Verify constant memory with large lists - ---- - -**Last Updated**: 2025-01-27 -**Status**: ✅ All advanced optimizations implemented diff --git a/docs/API_KEYS.md b/docs/API_KEYS.md index 40eb337..1029410 100644 --- a/docs/API_KEYS.md +++ b/docs/API_KEYS.md @@ -350,4 +350,4 @@ if status.get('running'): - [RBAC Documentation](RBAC.md) - Role-based access control - [API Documentation](API.md) - Complete API reference -- [Security Guide](SECURITY.md) - Security best practices +- [Security Hardening](SECURITY_HARDENING.md) - Security best practices diff --git a/docs/CI_CD.md b/docs/CI_CD.md index 824b89f..84f3eaf 100644 --- a/docs/CI_CD.md +++ b/docs/CI_CD.md @@ -322,7 +322,7 @@ The generated `.img` file includes: ```bash ssh pi@minecraft-server.local cd ~/minecraft-server - ./manage.sh status + ./scripts/manage.sh status ``` ## Automated Releases diff --git a/docs/CLEANUP_OPTIMIZATIONS_SUMMARY.md b/docs/CLEANUP_OPTIMIZATIONS_SUMMARY.md deleted file mode 100644 index e6174c5..0000000 --- a/docs/CLEANUP_OPTIMIZATIONS_SUMMARY.md +++ /dev/null @@ -1,165 +0,0 @@ -# Cleanup and Optimizations Summary - -This document summarizes the cleanup tasks and optimizations implemented to improve code quality, maintainability, and user experience. - -## ✅ Completed Optimizations - -### 1. React Hook Extraction and Code Reusability - -**Created Reusable Hooks:** - -- **`usePolling` Hook** (`web/src/hooks/usePolling.js`) - - - Centralizes polling logic used across multiple components - - Handles cleanup automatically - - Provides loading, error, and data states - - Used in: Dashboard, Players components - -- **`useErrorHandler` Hook** (`web/src/hooks/useErrorHandler.js`) - - Provides consistent error handling across components - - Integrates with toast notifications - - Reduces code duplication - -### 2. Players Page Improvements - -**Before:** - -- Non-functional KICK button -- Manual polling implementation -- Console.error statements -- No error handling - -**After:** - -- ✅ Functional KICK button with confirmation dialog -- ✅ Uses reusable `usePolling` hook -- ✅ Proper error handling with toast notifications -- ✅ Loading states during kick operation -- ✅ Improved key prop using player name instead of index - -### 3. Dashboard Component Optimization - -**Before:** - -- Manual polling with setInterval -- Console.error statements -- Inefficient re-renders -- Manual error handling - -**After:** - -- ✅ Uses `usePolling` hook for automatic data refresh -- ✅ `useCallback` for optimized function references -- ✅ Centralized error handling via `useErrorHandler` -- ✅ Cleaner, more maintainable code structure -- ✅ Automatic cleanup of intervals - -### 4. Code Quality Improvements - -- ✅ Removed unused variables and imports -- ✅ Improved component key props (using unique identifiers instead of indices) -- ✅ Better error messages with fallback defaults -- ✅ Consistent error handling patterns - -## 🔄 Remaining Cleanup Opportunities - -### High Priority - -1. **Console.log Cleanup** (11 files remaining) - - - Files: Analytics.jsx, Settings.jsx, Console.jsx, ConfigFiles.jsx, Plugins.jsx, Worlds.jsx, Logs.jsx, ApiKeys.jsx, Users.jsx, Backups.jsx, OAuthCallback.jsx - - **Note**: Some console.log statements in Logs.jsx and Console.jsx may be intentional for debugging WebSocket connections - - **Action**: Replace console.error with proper error handling hooks - - **Action**: Consider adding a debug mode flag for development-only console.log statements - -2. **Apply usePolling Hook to Other Components** - - - Analytics.jsx - Currently uses manual polling - - Worlds.jsx - Could benefit from polling hook - - Plugins.jsx - Could benefit from polling hook - -3. **Consolidate Duplicate API Patterns** - - Many components have similar try-catch-error handling patterns - - Extract to reusable hooks or utility functions - -### Medium Priority - -4. **API Server Code Consolidation** - - - Review `api/server.py` for duplicate endpoint patterns - - Extract common decorator logic - - Standardize error response formats - -5. **Task Documentation Cleanup** - - - Archive completed tasks from `TASKS.md` to separate file - - Keep active tasks only in main TASKS.md - -6. **Component Loading States** - - Standardize loading skeleton components - - Create reusable loading patterns - -### Low Priority - -7. **Performance Optimizations** - - - Implement React.memo for expensive components - - Consider virtualization for long lists (players, backups, logs) - - Lazy load routes for better initial load time - -8. **Accessibility Improvements** - - - Add ARIA labels to interactive elements - - Improve keyboard navigation - - Add focus indicators - -9. **Type Safety** - - Consider migrating to TypeScript - - Add PropTypes for better runtime type checking - - Document component prop types - -## 📊 Impact Assessment - -### Code Reduction - -- **Lines of Code Saved**: ~80-100 lines by extracting common patterns -- **Duplication Reduced**: Polling logic now centralized -- **Maintainability**: Improved with reusable hooks - -### Performance Improvements - -- **Re-render Optimization**: useCallback prevents unnecessary re-renders -- **Memory Leaks Prevented**: Automatic cleanup in hooks -- **Network Efficiency**: Consistent polling intervals - -### Developer Experience - -- **Easier to Add New Features**: Reusable hooks available -- **Consistent Patterns**: Standardized error handling -- **Better Testing**: Hooks can be tested independently - -## 🎯 Next Steps - -### Immediate Actions - -1. Apply `usePolling` hook to remaining components -2. Replace console.error statements with `useErrorHandler` -3. Add PropTypes or TypeScript for better type safety - -### Future Enhancements - -1. Create shared component library for common UI patterns -2. Implement error boundary components -3. Add performance monitoring -4. Consider state management solution (Redux/Zustand) if complexity grows - -## 📝 Notes - -- **WebSocket Logs**: Some console.log statements in Logs.jsx and Console.jsx are intentionally kept for debugging WebSocket connections. Consider adding a debug mode flag. -- **Backward Compatibility**: All changes maintain backward compatibility with existing functionality. -- **Testing**: New hooks should have unit tests added. - ---- - -**Last Updated**: 2025-01-27 -**Status**: In Progress - Core optimizations complete, cleanup tasks remaining diff --git a/docs/CLOUD_BACKUP.md b/docs/CLOUD_BACKUP.md index 717466f..279e1ff 100644 --- a/docs/CLOUD_BACKUP.md +++ b/docs/CLOUD_BACKUP.md @@ -210,7 +210,7 @@ fi 2. **Stop server**: ```bash - ./manage.sh stop + ./scripts/manage.sh stop ``` 3. **Restore backup**: @@ -223,7 +223,7 @@ fi 4. **Start server**: ```bash - ./manage.sh start + ./scripts/manage.sh start ``` ## Cost Considerations diff --git a/docs/CONFIGURATION_EXAMPLES.md b/docs/CONFIGURATION_EXAMPLES.md index 1d2eacc..d7b9c4d 100644 --- a/docs/CONFIGURATION_EXAMPLES.md +++ b/docs/CONFIGURATION_EXAMPLES.md @@ -313,8 +313,8 @@ services: Start both: ```bash -docker-compose up -d -docker-compose -f docker-compose-creative.yml up -d +docker compose up -d +docker compose -f docker-compose-creative.yml up -d ``` ## Backup Configurations @@ -325,7 +325,7 @@ Create backup script `backup-cron.sh`: ```bash #!/bin/bash cd /home/pi/minecraft-server -./manage.sh backup +./scripts/manage.sh backup # Keep only last 7 days of backups find ./backups -name "minecraft_backup_*.tar.gz" -mtime +7 -delete @@ -403,10 +403,10 @@ environment: After changing configuration: -1. Stop server: `./manage.sh stop` +1. Stop server: `./scripts/manage.sh stop` 2. Edit configuration files -3. Start server: `./manage.sh start` -4. Monitor logs: `./manage.sh logs` +3. Start server: `./scripts/manage.sh start` +4. Monitor logs: `./scripts/manage.sh logs` 5. Test in-game 6. Check resources: `htop` and `docker stats` diff --git a/docs/CONSOLIDATION_SUMMARY.md b/docs/CONSOLIDATION_SUMMARY.md deleted file mode 100644 index 5e4041d..0000000 --- a/docs/CONSOLIDATION_SUMMARY.md +++ /dev/null @@ -1,262 +0,0 @@ -# Documentation Consolidation Summary - -This document summarizes the documentation consolidation completed on 2025-01-27. - -## Overview - -The documentation has been reorganized and consolidated to reduce redundancy, improve navigation, and create single comprehensive guides for each major topic. - -## Results - -### Before Consolidation - -- **~60 documentation files** in `docs/` directory -- Multiple overlapping files covering similar topics -- Duplicate information across files -- Difficult to find specific information - -### After Consolidation - -- **43 active documentation files** (reduced by ~28%) -- **17 files archived** (preserved for historical reference) -- Single comprehensive guide for each major topic -- Clearer organization and easier navigation - -## Consolidations Completed - -### 1. CI/CD Documentation ✅ - -**Before**: 4 separate files - -- `CI_CD.md` -- `CI_CD_PIPELINE.md` -- `CI_CD_OPTIMIZATIONS.md` -- `CI_CD_ENHANCEMENTS.md` - -**After**: 1 comprehensive file - -- `CI_CD.md` - Complete CI/CD guide covering: - - Pipeline structure - - Optimizations - - Testing enhancements - - Release process - - Troubleshooting - -**Archived**: 3 files moved to `docs/archive/` - -### 2. API Documentation ✅ - -**Before**: 2 separate files - -- `API.md` - Usage guide -- `API_DOCUMENTATION.md` - OpenAPI specification guide - -**After**: 1 comprehensive file - -- `API.md` - Complete REST API documentation with: - - Quick start guide - - Authentication methods - - Complete endpoint reference - - Usage examples (Python, cURL, JavaScript) - - OpenAPI specification details - - Developer tools - -**Archived**: 1 file moved to `docs/archive/` - -### 3. Testing Documentation ✅ - -**Before**: 4 separate files - -- `TESTING.md` - Main testing guide -- `TESTING_COMPLETE.md` - Implementation summary -- `TESTING_FINAL_SUMMARY.md` - Final summary -- `TESTING_ENHANCEMENTS.md` - Framework enhancements - -**After**: 1 comprehensive file - -- `TESTING.md` - Complete testing guide with: - - Quick start - - Test structure and types - - Writing tests - - Testing framework enhancements section - - Coverage analysis - - Troubleshooting - -**Archived**: 3 files moved to `docs/archive/` - -### 4. Raspberry Pi Documentation ✅ - -**Before**: Summary files alongside main guides - -- `RASPBERRY_PI_OPTIMIZATIONS.md` - Main guide -- `RASPBERRY_PI_COMPATIBILITY.md` - Main guide -- `RPI5_OPTIMIZATIONS_SUMMARY.md` - Quick reference -- `RPI5_ACTION_CHECKLIST.md` - Verification checklist - -**After**: Main comprehensive guides retained - -- `RASPBERRY_PI_OPTIMIZATIONS.md` - Complete optimization guide -- `RASPBERRY_PI_COMPATIBILITY.md` - Complete compatibility guide - -**Archived**: 2 summary/checklist files moved to `docs/archive/` - -### 5. Minecraft Gameplay Documentation ✅ - -**Before**: 2 separate files - -- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Enhancement roadmap -- `GAMEPLAY_FEATURES_IMPLEMENTED.md` - Implementation summary - -**After**: 1 comprehensive file - -- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Complete guide with: - - Current gameplay features - - Recently implemented P1 features section - - Future enhancement roadmap - -**Archived**: 1 file moved to `docs/archive/` - -### 6. Summary Files ✅ - -**Archived**: Historical summary files - -- `SUMMARY.md` - Project analysis summary (info in CHANGELOG/ROADMAP) -- `CONSOLIDATION_NOTES.md` - Historical consolidation notes - -## Files Archived - -Total: **17 files** in `docs/archive/` - -### CI/CD Related - -- `CI_CD_PIPELINE.md` -- `CI_CD_OPTIMIZATIONS.md` -- `CI_CD_ENHANCEMENTS.md` - -### API Related - -- `API_DOCUMENTATION.md` - -### Testing Related - -- `TESTING_COMPLETE.md` -- `TESTING_FINAL_SUMMARY.md` -- `TESTING_ENHANCEMENTS.md` - -### RPI Related - -- `RPI5_OPTIMIZATIONS_SUMMARY.md` -- `RPI5_ACTION_CHECKLIST.md` - -### Minecraft Related - -- `GAMEPLAY_FEATURES_IMPLEMENTED.md` - -### Implementation Summaries - -- `IMPLEMENTATION_SUMMARY.md` -- `IMPLEMENTATION_SUMMARY_P1.md` -- `IMPLEMENTATION_SUMMARY_docs.md` -- `FINAL_IMPLEMENTATION_SUMMARY.md` - -### Other - -- `SUMMARY.md` -- `CONSOLIDATION_NOTES.md` -- `README.md` (archive index) - -## Updated Files - -### Documentation Files - -- `CI_CD.md` - Completely rewritten with all content consolidated -- `API.md` - Enhanced with OpenAPI specification details -- `TESTING.md` - Enhanced with testing framework enhancements section -- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Updated with implementation status -- `INDEX.md` - Updated to reflect consolidated structure -- `README.md` - Updated structure section - -### Archive Files - -- `archive/README.md` - Updated with list of all archived files - -## Benefits Achieved - -1. **Reduced Redundancy** ✅ - - - Eliminated duplicate information - - Single source of truth for each topic - -2. **Easier Navigation** ✅ - - - Fewer files to search through - - Clearer organization in INDEX.md - - Better categorization - -3. **Better Organization** ✅ - - - Comprehensive guides for major topics - - Historical documents preserved in archive - - Clear separation between active and archived docs - -4. **Improved Maintainability** ✅ - - - Single file to update for each major topic - - Less risk of information getting out of sync - - Easier to keep documentation current - -5. **Historical Preservation** ✅ - - All archived files preserved for reference - - Archive README documents what was consolidated - - Can reference archived files if needed - -## Current Documentation Structure - -### Main Guides (Comprehensive) - -- `CI_CD.md` - CI/CD pipeline (consolidated) -- `API.md` - REST API (consolidated) -- `TESTING.md` - Testing framework (consolidated) -- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Gameplay enhancements (updated) - -### Specialized Reference Guides (Kept Separate) - -- `TEST_COVERAGE.md` - Coverage analysis -- `WEB_UI_TESTING.md` - Frontend testing -- `ANALYTICS.md` - Analytics features - -### All Other Guides (Unchanged) - -- Installation, user guides, developer guides remain as-is - -## Navigation - -Use **[INDEX.md](INDEX.md)** as the starting point for all documentation. It provides: - -- Organized categories -- Quick navigation links -- Clear structure -- Links to all active documentation - -## Future Maintenance - -When adding new documentation: - -1. **Check existing guides first** - Add to existing comprehensive guides when possible -2. **Follow INDEX.md structure** - Place new docs in appropriate category -3. **Update INDEX.md** - Add new documentation links -4. **Avoid summary files** - Use CHANGELOG.md for implementation summaries -5. **Keep guides comprehensive** - Prefer enhancing existing guides over creating new summary files - -## Questions? - -- See [INDEX.md](INDEX.md) for navigation -- Check [archive/README.md](archive/README.md) for archived file information -- Reference [CHANGELOG.md](../CHANGELOG.md) for version history - ---- - -**Consolidation Date**: 2025-01-27 -**Files Reduced**: ~60 → 43 active files (~28% reduction) -**Files Archived**: 17 files -**Status**: ✅ Complete diff --git a/docs/CURSOR_CONFIGURATION.md b/docs/CURSOR_CONFIGURATION.md index b22198c..95d50a0 100644 --- a/docs/CURSOR_CONFIGURATION.md +++ b/docs/CURSOR_CONFIGURATION.md @@ -14,18 +14,27 @@ Cursor IDE uses various configuration files to provide: ## Configuration Files -### `.cursorrules` +### AI assistant instructions -**Purpose**: AI agent instructions for consistent development across sessions. +**Source of truth**: [`AGENTS.md`](../AGENTS.md) in the project root. It defines the +stack, commands, code standards, testing layout and conventions. -**Location**: Project root +Every editor-specific file is a thin pointer to it — edit `AGENTS.md`, never these: -**Usage**: Automatically loaded by Cursor IDE to guide AI assistants. - -**See Also**: [AGENT_INSTRUCTIONS.md](../AGENT_INSTRUCTIONS.md) +| File | Read by | +| --- | --- | +| `.cursor/rules/project.mdc` | Cursor (rules format, always applied) | +| `.cursorrules` | Cursor (legacy format) | +| `CLAUDE.md` | Claude Code — plus a few Claude-specific notes | +| `.github/copilot-instructions.md` | GitHub Copilot (older setups; newer ones read `AGENTS.md` directly) | +| `.clinerules` | Cline | +| `.windsurfrules` | Windsurf | --- +> **Note**: `.vscode/` is gitignored, so the files below are not in the repository — +> they are per-developer. The sections describe what to put in them if you want them. + ### `.vscode/settings.json` **Purpose**: Workspace-specific editor settings for Cursor/VS Code. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 016ecbd..8812c6e 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -75,7 +75,7 @@ bash -n manage.sh bash -n start.sh # Test docker-compose -docker-compose config +docker compose config # Test server startup (requires Docker) make build @@ -102,7 +102,7 @@ make logs - 2-space indentation - Use environment variables - Keep lines under 120 characters -- Validate with `docker-compose config` +- Validate with `docker compose config` ### Documentation - Markdown format diff --git a/docs/DOCKER_COMPOSE_FIX.md b/docs/DOCKER_COMPOSE_FIX.md deleted file mode 100644 index d86b0aa..0000000 --- a/docs/DOCKER_COMPOSE_FIX.md +++ /dev/null @@ -1,147 +0,0 @@ -# Quick Fix: Docker Compose Installation Conflict - -## Prerequisites: Install Docker First - -**If you see `docker: command not found`**, you need to install Docker first: - -```bash -# Install Docker -curl -fsSL https://get.docker.com -o get-docker.sh -sudo sh get-docker.sh -sudo usermod -aG docker $USER -rm get-docker.sh - -# IMPORTANT: Log out and back in for Docker permissions -exit -# Then SSH back in: ssh pi@docker-server.local - -# Verify Docker is installed -docker --version -docker compose version -``` - -After installing Docker, the `docker-compose-plugin` is automatically included, so you don't need to install `docker-compose` separately. - ---- - -## The Problem - -You're getting this error when trying to install `docker-compose`: - -``` -dpkg: error processing archive ... trying to overwrite '/usr/libexec/docker/cli-plugins/docker-compose', -which is also in package docker-compose-plugin -``` - -## The Solution - -The `docker-compose-plugin` is already installed with your Docker installation. You don't need the standalone `docker-compose` package. - -### Quick Fix (Run These Commands) - -```bash -# 1. Clean up the broken package state -sudo apt-get remove --purge docker-compose -sudo apt-get autoremove -sudo apt-get autoclean - -# 2. Verify docker compose plugin works -docker compose version - -# You should see something like: -# Docker Compose version v2.40.3 -``` - -### Use Docker Compose Plugin - -Instead of `docker-compose` (with hyphen), use `docker compose` (with space): - -```bash -# Old way (standalone): -docker-compose up -d - -# New way (plugin): -docker compose up -d -``` - -### All Docker Compose Commands - -Replace all instances of `docker-compose` with `docker compose`: - -| Old Command | New Command | -| ------------------------ | ------------------------ | -| `docker-compose up` | `docker compose up` | -| `docker-compose down` | `docker compose down` | -| `docker-compose pull` | `docker compose pull` | -| `docker-compose build` | `docker compose build` | -| `docker-compose logs` | `docker compose logs` | -| `docker-compose ps` | `docker compose ps` | -| `docker-compose restart` | `docker compose restart` | - -### Update Systemd Services - -If you have any systemd service files using `docker-compose`, update them: - -```bash -# Edit the service file -sudo nano /etc/systemd/system/your-service.service - -# Change: -ExecStart=/usr/bin/docker-compose up -d - -# To: -ExecStart=/usr/bin/docker compose up -d -``` - -Then reload systemd: - -```bash -sudo systemctl daemon-reload -sudo systemctl restart your-service.service -``` - -## Why This Happens - -Modern Docker installations (Docker Engine 20.10+) include Docker Compose as a plugin. The plugin is installed as part of the Docker package and provides the same functionality as the standalone `docker-compose` package, but integrated directly into Docker. - -The plugin approach is: - -- ✅ More integrated with Docker -- ✅ Automatically updated with Docker -- ✅ Better performance -- ✅ Recommended by Docker - -## Verification - -After fixing, verify everything works: - -```bash -# Check Docker Compose version -docker compose version - -# Test with a simple command -docker compose --help - -# If you have a docker-compose.yml, test it -docker compose config -``` - -## Still Having Issues? - -If `docker compose version` doesn't work, the plugin might not be installed: - -```bash -# Install the plugin -sudo apt-get update -sudo apt-get install -y docker-compose-plugin - -# Verify -docker compose version -``` - -## Summary - -1. ✅ Remove broken `docker-compose` package -2. ✅ Use `docker compose` (with space) instead of `docker-compose` (with hyphen) -3. ✅ Update any systemd services or scripts -4. ✅ You're all set! diff --git a/docs/DOCUMENTATION_CONSOLIDATION_PLAN.md b/docs/DOCUMENTATION_CONSOLIDATION_PLAN.md deleted file mode 100644 index 8050adf..0000000 --- a/docs/DOCUMENTATION_CONSOLIDATION_PLAN.md +++ /dev/null @@ -1,119 +0,0 @@ -# Documentation Consolidation Summary - -This document summarizes the documentation consolidation that has been completed to improve organization and reduce redundancy. - -## ✅ Completed Consolidations - -### 1. CI/CD Documentation - -- **Consolidated into**: `CI_CD.md` -- **Merged files**: - - `CI_CD_PIPELINE.md` - Pipeline structure details - - `CI_CD_OPTIMIZATIONS.md` - Performance optimizations - - `CI_CD_ENHANCEMENTS.md` - Testing enhancements in CI/CD -- **Archived**: All three files moved to `docs/archive/` -- **Result**: Single comprehensive CI/CD guide covering all aspects - -### 2. API Documentation - -- **Consolidated into**: `API.md` -- **Merged files**: - - `API_DOCUMENTATION.md` - OpenAPI specification and developer docs -- **Archived**: `API_DOCUMENTATION.md` -- **Result**: Single comprehensive API guide with both usage examples and OpenAPI specification details - -### 3. Testing Documentation - -- **Consolidated into**: `TESTING.md` -- **Merged files**: - - `TESTING_ENHANCEMENTS.md` - Testing framework enhancements -- **Archived**: - - `TESTING_COMPLETE.md` - Implementation summary - - `TESTING_FINAL_SUMMARY.md` - Final summary - - `TESTING_ENHANCEMENTS.md` - Framework enhancements (merged) -- **Result**: Single comprehensive testing guide with enhancements section - -### 4. Raspberry Pi Documentation - -- **Archived files**: - - `RPI5_OPTIMIZATIONS_SUMMARY.md` - Quick reference (redundant with main guide) - - `RPI5_ACTION_CHECKLIST.md` - Verification checklist (information in compatibility guide) -- **Result**: Main comprehensive guides remain (`RASPBERRY_PI_OPTIMIZATIONS.md`, `RASPBERRY_PI_COMPATIBILITY.md`) - -### 5. Minecraft Gameplay Documentation - -- **Updated**: `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` -- **Merged files**: - - `GAMEPLAY_FEATURES_IMPLEMENTED.md` - Implementation summary -- **Archived**: `GAMEPLAY_FEATURES_IMPLEMENTED.md` -- **Result**: Single gameplay enhancements guide with implementation status included - -### 6. Summary Files - -- **Archived**: - - `SUMMARY.md` - Project analysis summary (information in CHANGELOG and ROADMAP) - - `CONSOLIDATION_NOTES.md` - Historical consolidation notes -- **Result**: Information accessible through current documentation structure - -## Archive Directory - -All archived files are located in `docs/archive/`. See [archive/README.md](archive/README.md) for details. - -**Total files archived**: 11 files - -## Benefits Achieved - -1. **Reduced Redundancy** - Eliminated duplicate information across multiple files -2. **Easier Navigation** - Fewer files to search through (reduced from ~60 to ~48 docs) -3. **Better Organization** - Clearer structure with comprehensive guides -4. **Maintainability** - Single source of truth for each topic -5. **Historical Preservation** - Archived files preserved for reference - -## Current Documentation Structure - -### Main Guides (Consolidated) - -- `CI_CD.md` - Complete CI/CD pipeline guide -- `API.md` - Complete REST API documentation -- `TESTING.md` - Complete testing guide with enhancements -- `MINECRAFT_GAMEPLAY_ENHANCEMENTS.md` - Gameplay enhancements roadmap with implementation status - -### Reference Guides (Unchanged) - -- `TEST_COVERAGE.md` - Coverage analysis guide (kept separate as specialized reference) -- `WEB_UI_TESTING.md` - Frontend testing guide (kept separate as specialized reference) -- `ANALYTICS.md` - Analytics features guide (not a test doc, kept separate) - -## Files Removed from Active Docs - -The following files have been archived (accessible in `docs/archive/`): - -- CI/CD related: `CI_CD_PIPELINE.md`, `CI_CD_OPTIMIZATIONS.md`, `CI_CD_ENHANCEMENTS.md` -- API related: `API_DOCUMENTATION.md` -- Testing related: `TESTING_COMPLETE.md`, `TESTING_FINAL_SUMMARY.md`, `TESTING_ENHANCEMENTS.md` -- RPI related: `RPI5_OPTIMIZATIONS_SUMMARY.md`, `RPI5_ACTION_CHECKLIST.md` -- Minecraft related: `GAMEPLAY_FEATURES_IMPLEMENTED.md` -- Summary files: `SUMMARY.md`, `CONSOLIDATION_NOTES.md` - -## Documentation Index Updated - -The [INDEX.md](INDEX.md) has been updated to: - -- Remove references to archived files -- Add links to consolidated guides -- Include note about archived documentation -- Reflect current documentation structure - -## Future Maintenance - -When adding new documentation: - -1. **Check existing guides** - Add to existing comprehensive guides when possible -2. **Use INDEX.md** - Follow the structure outlined in INDEX.md -3. **Update INDEX.md** - Add new documentation to the appropriate section -4. **Avoid summaries** - Use CHANGELOG.md for implementation summaries instead of separate files - ---- - -**Consolidation Date**: 2025-01-27 -**Status**: ✅ Complete diff --git a/docs/INDEX.md b/docs/INDEX.md index 90b6895..5e09746 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -1,225 +1,122 @@ # Documentation Index -Complete guide to all project documentation, organized by category. +Every guide in this project, grouped by what you are trying to do. -## 📚 Quick Navigation - -- **[Getting Started](#getting-started)** - Installation and setup -- **[User Guides](#user-guides)** - How to use features -- **[Developer Guides](#developer-guides)** - Contributing and development -- **[Reference](#reference)** - Quick references and examples -- **[Configuration](#configuration)** - Configuration guides -- **[Troubleshooting](#troubleshooting)** - Problem solving +- [Getting Started](#getting-started) +- [Deployment & Operations](#deployment--operations) +- [Server Features](#server-features) +- [API & Web Panel](#api--web-panel) +- [Performance & Raspberry Pi](#performance--raspberry-pi) +- [Development](#development) +- [Reference & Troubleshooting](#reference--troubleshooting) --- ## Getting Started -### Installation & Setup - -- **[RPI5_FULL_DEPLOYMENT.md](RPI5_FULL_DEPLOYMENT.md)** - Complete guide for deploying all components (Minecraft, API, Web) on Raspberry Pi 5 -- **[DOCKER_DEPLOYMENT_FLOW.md](DOCKER_DEPLOYMENT_FLOW.md)** - How Docker images are deployed from CI to Raspberry Pi -- **[AUTO_DEPLOYMENT_SETUP.md](AUTO_DEPLOYMENT_SETUP.md)** - Step-by-step guide for automatic deployment setup -- **[UPDATE_DOCKER_IMAGE.md](UPDATE_DOCKER_IMAGE.md)** - How to check, pull, and update to the latest Docker image -- **[UPDATE_CODEBASE.md](UPDATE_CODEBASE.md)** - How to update the GitHub repository code on Raspberry Pi 5 -- **[API_VENV_SETUP.md](API_VENV_SETUP.md)** - How to set up and use Python virtual environment for API server -- **[SYSTEM_OPTIMIZATIONS.md](SYSTEM_OPTIMIZATIONS.md)** - Comprehensive system and filesystem optimizations for Raspberry Pi 5 -- **[RASPBERRY_PI_COMPATIBILITY.md](RASPBERRY_PI_COMPATIBILITY.md)** - Raspberry Pi 5 compatibility guide and verification steps -- **[RASPBERRY_PI_OPTIMIZATIONS.md](RASPBERRY_PI_OPTIMIZATIONS.md)** - Performance optimizations and enhancements for Raspberry Pi 5 -- **[DOCKER_BOOT_SETUP.md](DOCKER_BOOT_SETUP.md)** - Configure Raspberry Pi 5 to boot and automatically pull/run Docker images -- **[INSTALL.md](INSTALL.md)** - Complete installation guide for Raspberry Pi 5 -- **[README.md](../README.md)** - Project overview and quick start - -### First Steps +| Guide | What it covers | +| --- | --- | +| [INSTALL.md](INSTALL.md) | Full installation on a Raspberry Pi 5, start to finish | +| [QUICK_REFERENCE.md](QUICK_REFERENCE.md) | One-page command cheat sheet | +| [CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md) | Worked examples for every config file | +| [MINECRAFT_SERVER_SETUP.md](MINECRAFT_SERVER_SETUP.md) | Getting the Minecraft server itself running with auto-start | -1. Read [INSTALL.md](INSTALL.md) for installation -2. Review [QUICK_REFERENCE.md](QUICK_REFERENCE.md) for common commands -3. Check [CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md) for configuration +New here? Read `INSTALL.md`, then keep `QUICK_REFERENCE.md` open. --- -## User Guides - -### Core Features - -- **[BACKUP_AND_MONITORING.md](BACKUP_AND_MONITORING.md)** - Backup scheduling, retention, and monitoring -- **[CLOUD_BACKUP.md](CLOUD_BACKUP.md)** - Cloud backup integration (R2, S3, B2) -- **[UPDATE_MANAGEMENT.md](UPDATE_MANAGEMENT.md)** - Server updates and version management -- **[PLUGIN_MANAGEMENT.md](PLUGIN_MANAGEMENT.md)** - Installing and managing plugins -- **[MOD_SUPPORT.md](MOD_SUPPORT.md)** - Mod loader detection and mod pack installation -- **[MINECRAFT_ENHANCEMENTS.md](MINECRAFT_ENHANCEMENTS.md)** - Minecraft-specific enhancements and configurations -- **[MINECRAFT_GAMEPLAY_ENHANCEMENTS.md](MINECRAFT_GAMEPLAY_ENHANCEMENTS.md)** - Gameplay enhancement roadmap (includes implemented P1 features) -- **[MINECRAFT_MANAGEMENT.md](MINECRAFT_MANAGEMENT.md)** - Minecraft server management tools and scripts -- **[MULTI_WORLD.md](MULTI_WORLD.md)** - Managing multiple worlds -- **[LOG_MANAGEMENT.md](LOG_MANAGEMENT.md)** - Log rotation, search, and analysis - -### Advanced Features - -- **[RCON.md](RCON.md)** - Remote Console (RCON) setup and usage -- **[API.md](API.md)** - Complete REST API documentation (includes OpenAPI spec) -- **[WEB_INTERFACE.md](WEB_INTERFACE.md)** - Web admin panel guide -- **[RBAC.md](RBAC.md)** - Role-Based Access Control (RBAC) system -- **[API_KEYS.md](API_KEYS.md)** - API key management and usage -- **[DYNAMIC_DNS.md](DYNAMIC_DNS.md)** - Dynamic DNS integration (DuckDNS, No-IP, Cloudflare) -- **[ANALYTICS.md](ANALYTICS.md)** - Analytics and monitoring capabilities +## Deployment & Operations + +| Guide | What it covers | +| --- | --- | +| [RPI5_FULL_DEPLOYMENT.md](RPI5_FULL_DEPLOYMENT.md) | Deploying all components (server, API, web) together | +| [DOCKER_BOOT_SETUP.md](DOCKER_BOOT_SETUP.md) | Pulling and running Docker images automatically at boot | +| [DOCKER_DEPLOYMENT_FLOW.md](DOCKER_DEPLOYMENT_FLOW.md) | How an image gets from CI to the Pi | +| [AUTO_DEPLOYMENT_SETUP.md](AUTO_DEPLOYMENT_SETUP.md) | Wiring up automatic deployment | +| [UPDATE_DOCKER_IMAGE.md](UPDATE_DOCKER_IMAGE.md) | Checking for and pulling a newer image | +| [UPDATE_CODEBASE.md](UPDATE_CODEBASE.md) | Updating the repository checkout on the Pi | +| [UPDATE_MANAGEMENT.md](UPDATE_MANAGEMENT.md) | Minecraft version updates and compatibility checks | +| [MULTI_ARCHITECTURE.md](MULTI_ARCHITECTURE.md) | Building images for arm64 and amd64 | +| [BACKUP_AND_MONITORING.md](BACKUP_AND_MONITORING.md) | Backup scheduling, retention, health checks, metrics | +| [CLOUD_BACKUP.md](CLOUD_BACKUP.md) | Offsite backups to Cloudflare R2, S3 or Backblaze B2 | +| [LOG_MANAGEMENT.md](LOG_MANAGEMENT.md) | Log rotation, search and analysis | +| [DYNAMIC_DNS.md](DYNAMIC_DNS.md) | Keeping a hostname pointed at a changing home IP | +| [CLOUDFLARE_SETUP.md](CLOUDFLARE_SETUP.md) | Cloudflare DDNS configuration specifics | --- -## Developer Guides - -### Development Setup - -- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Development environment setup and workflow -- **[CURSOR_CONFIGURATION.md](CURSOR_CONFIGURATION.md)** - Cursor IDE configuration guide -- **[LINTING.md](LINTING.md)** - Code linting and static analysis -- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Contribution guidelines - -### Project Planning - -- **[ROADMAP.md](ROADMAP.md)** - Development roadmap and future plans -- **[TASKS.md](TASKS.md)** - Detailed task breakdown with priorities +## Server Features -### Workspace - -- **[WORKSPACE_ENHANCEMENTS.md](WORKSPACE_ENHANCEMENTS.md)** - Workspace optimizations summary -- **[AGENT_INSTRUCTIONS.md](../AGENT_INSTRUCTIONS.md)** - AI agent instructions for consistency +| Guide | What it covers | +| --- | --- | +| [MINECRAFT_MANAGEMENT.md](MINECRAFT_MANAGEMENT.md) | Whitelist, bans, ops, server properties, announcements | +| [MINECRAFT_ENHANCEMENTS.md](MINECRAFT_ENHANCEMENTS.md) | Minecraft-specific tuning and configuration | +| [MINECRAFT_GAMEPLAY_ENHANCEMENTS.md](MINECRAFT_GAMEPLAY_ENHANCEMENTS.md) | Gameplay feature set and roadmap | +| [MULTI_WORLD.md](MULTI_WORLD.md) | Creating, switching and backing up multiple worlds | +| [PLUGIN_MANAGEMENT.md](PLUGIN_MANAGEMENT.md) | Installing and configuring Bukkit/Spigot/Paper plugins | +| [MOD_SUPPORT.md](MOD_SUPPORT.md) | Mod loader detection and mod pack installation | +| [RCON.md](RCON.md) | Remote console setup and usage | +| [ANALYTICS.md](ANALYTICS.md) | Player and server analytics collection and reports | --- -## Reference - -### Quick References - -- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Command reference and cheat sheet -- **[CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md)** - Configuration file examples +## API & Web Panel -### Testing & Code Quality - -- **[TESTING.md](TESTING.md)** - Complete testing guide with framework enhancements -- **[TEST_COVERAGE.md](TEST_COVERAGE.md)** - Test coverage analysis and gap identification -- **[WEB_UI_TESTING.md](WEB_UI_TESTING.md)** - Frontend testing guide -- **[LINTING.md](LINTING.md)** - Code linting and static analysis guide -- **[DOCKER_OPTIMIZATION.md](DOCKER_OPTIMIZATION.md)** - Docker image optimization guide -- **[DOCKER_BOOT_SETUP.md](DOCKER_BOOT_SETUP.md)** - Configure Raspberry Pi 5 to boot and automatically pull/run Docker images -- **[PERFORMANCE_BENCHMARKING.md](PERFORMANCE_BENCHMARKING.md)** - Performance benchmarking and regression testing -- **[MULTI_ARCHITECTURE.md](MULTI_ARCHITECTURE.md)** - Multi-architecture build and deployment guide -- **[CI_CD.md](CI_CD.md)** - Complete CI/CD pipeline guide (consolidated) +| Guide | What it covers | +| --- | --- | +| [API.md](API.md) | Complete REST API reference (mirrors `api/openapi.yaml`) | +| [API_VENV_SETUP.md](API_VENV_SETUP.md) | Python virtual environment for the API server | +| [API_KEYS.md](API_KEYS.md) | Creating, scoping and rotating API keys | +| [RBAC.md](RBAC.md) | Roles and permissions | +| [OAUTH_SETUP.md](OAUTH_SETUP.md) | Google / Apple sign-in | +| [WEB_INTERFACE.md](WEB_INTERFACE.md) | Using the React admin panel | +| [SECURITY_HARDENING.md](SECURITY_HARDENING.md) | Hardening the API and the host | --- -## Configuration - -### Configuration Files +## Performance & Raspberry Pi -- **[config/README.md](../config/README.md)** - Configuration directory structure -- **[CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md)** - Example configurations - -### Environment Variables - -See [INSTALL.md](INSTALL.md) and [DEVELOPMENT.md](DEVELOPMENT.md) for environment variable setup. +| Guide | What it covers | +| --- | --- | +| [RASPBERRY_PI_COMPATIBILITY.md](RASPBERRY_PI_COMPATIBILITY.md) | What works on which Pi, and how to verify | +| [RASPBERRY_PI_OPTIMIZATIONS.md](RASPBERRY_PI_OPTIMIZATIONS.md) | Pi-specific tuning (memory, JVM, thermals) | +| [SYSTEM_OPTIMIZATIONS.md](SYSTEM_OPTIMIZATIONS.md) | OS and filesystem tuning | +| [DOCKER_OPTIMIZATION.md](DOCKER_OPTIMIZATION.md) | Image size, build caching, layer strategy | +| [PERFORMANCE_BENCHMARKING.md](PERFORMANCE_BENCHMARKING.md) | Measuring and comparing performance | --- -## Troubleshooting - -- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common problems and solutions -- **[LOG_MANAGEMENT.md](LOG_MANAGEMENT.md)** - Log analysis and debugging - ---- +## Development -## Project Information +| Guide | What it covers | +| --- | --- | +| [DEVELOPMENT.md](DEVELOPMENT.md) | Local setup and day-to-day workflow | +| [TESTING.md](TESTING.md) | Test layout, how to run each suite, coverage | +| [WEB_UI_TESTING.md](WEB_UI_TESTING.md) | Vitest, MSW and Playwright specifics for `web/` | +| [LINTING.md](LINTING.md) | ShellCheck, ESLint, flake8, yamllint | +| [CI_CD.md](CI_CD.md) | GitHub Actions pipeline and release process | +| [CURSOR_CONFIGURATION.md](CURSOR_CONFIGURATION.md) | Cursor IDE setup | +| [ROADMAP.md](ROADMAP.md) | Planned work, by phase | +| [TASKS.md](TASKS.md) | Detailed task backlog | -- **[CHANGELOG.md](../CHANGELOG.md)** - Version history and changes -- **[LICENSE](../LICENSE)** - Project license -- **[README.md](../README.md)** - Main project documentation +AI assistants read [`../AGENTS.md`](../AGENTS.md) — the single source of truth for +conventions. See also [`../CONTRIBUTING.md`](../CONTRIBUTING.md). --- -## Documentation by Topic +## Reference & Troubleshooting -### Server Management - -- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Commands -- [UPDATE_MANAGEMENT.md](UPDATE_MANAGEMENT.md) - Updates -- [RCON.md](RCON.md) - Remote control - -### Data Management - -- [BACKUP_AND_MONITORING.md](BACKUP_AND_MONITORING.md) - Backups -- [MULTI_WORLD.md](MULTI_WORLD.md) - Worlds -- [LOG_MANAGEMENT.md](LOG_MANAGEMENT.md) - Logs - -### Extensions - -- [PLUGIN_MANAGEMENT.md](PLUGIN_MANAGEMENT.md) - Plugins -- [UPDATE_MANAGEMENT.md](UPDATE_MANAGEMENT.md) - Server types - -### Development - -- [DEVELOPMENT.md](DEVELOPMENT.md) - Setup -- [TESTING.md](TESTING.md) - Testing -- [API.md](API.md) - API development - -### Integration - -- [API.md](API.md) - REST API -- [WEB_INTERFACE.md](WEB_INTERFACE.md) - Web panel -- [RCON.md](RCON.md) - RCON protocol -- [RBAC.md](RBAC.md) - Role-based access control -- [API_KEYS.md](API_KEYS.md) - API key management - ---- - -## Documentation Structure - -``` -docs/ -├── INDEX.md # This file - navigation hub -├── INSTALL.md # Installation guide -├── QUICK_REFERENCE.md # Command reference -├── CONFIGURATION_EXAMPLES.md # Config examples -├── TROUBLESHOOTING.md # Problem solving -│ -├── User Guides/ -│ ├── BACKUP_AND_MONITORING.md -│ ├── UPDATE_MANAGEMENT.md -│ ├── PLUGIN_MANAGEMENT.md -│ ├── MULTI_WORLD.md -│ ├── LOG_MANAGEMENT.md -│ ├── RCON.md -│ ├── API.md -│ ├── WEB_INTERFACE.md -│ ├── RBAC.md -│ └── API_KEYS.md -│ -└── Developer Guides/ - ├── DEVELOPMENT.md - ├── TESTING.md - ├── ROADMAP.md - ├── CURSOR_CONFIGURATION.md - └── WORKSPACE_ENHANCEMENTS.md -``` - ---- - -## Getting Help - -1. **Check the documentation** - Start with [QUICK_REFERENCE.md](QUICK_REFERENCE.md) or [TROUBLESHOOTING.md](TROUBLESHOOTING.md) -2. **Search existing issues** - Check GitHub issues for similar problems -3. **Ask for help** - Open a GitHub issue with: - - What you're trying to do - - What happened vs what you expected - - Relevant log output - - Your configuration +| Guide | What it covers | +| --- | --- | +| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Installation, startup, restart loops, connectivity, Docker, system issues | +| [QUICK_REFERENCE.md](QUICK_REFERENCE.md) | Command cheat sheet | +| [CONFIGURATION_EXAMPLES.md](CONFIGURATION_EXAMPLES.md) | Config file examples | +| [../CHANGELOG.md](../CHANGELOG.md) | Version history | --- -## Archived Documentation - -Some documentation files have been consolidated and archived. See [archive/README.md](archive/README.md) for details. - -**Note**: All information from archived files has been integrated into the current documentation structure. - ---- +## Adding a Document -**Last Updated**: 2025-01-27 +Add the file to `docs/`, then add a row to the right table above — an unlisted +document will not be found. Historical "summary" or "implementation complete" +write-ups do not belong here; that record lives in `CHANGELOG.md` and git history. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 7308f54..59a7e2f 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -162,10 +162,10 @@ ls -la ```bash # Make setup script executable -chmod +x setup-rpi.sh +chmod +x scripts/setup-rpi.sh # Run setup script -./setup-rpi.sh +./scripts/setup-rpi.sh ``` The setup script will: @@ -192,7 +192,7 @@ ssh pi@minecraft-server.local # Verify Docker works without sudo docker --version -docker-compose --version +docker compose --version ``` ### Step 7: Configure Server (Optional) @@ -220,17 +220,17 @@ Press `Ctrl+X`, then `Y`, then `Enter` to save changes. cd ~/minecraft-server # Make management script executable -chmod +x manage.sh +chmod +x scripts/manage.sh # Start the server -./manage.sh start +./scripts/manage.sh start ``` ### Monitor Startup ```bash # View logs (Press Ctrl+C to exit) -./manage.sh logs +./scripts/manage.sh logs ``` First startup takes 5-10 minutes as it: @@ -305,7 +305,7 @@ Share this IP with friends: `YOUR.PUBLIC.IP:25565` ### Check Server Status ```bash -./manage.sh status +./scripts/manage.sh status ``` Should show container as "Up". @@ -332,7 +332,7 @@ docker stats minecraft-server ### Create First Backup ```bash -./manage.sh backup +./scripts/manage.sh backup ``` ## Troubleshooting @@ -347,7 +347,7 @@ sudo systemctl status docker sudo systemctl start docker # Check detailed error logs -docker-compose logs +docker compose logs ``` ### Memory Issues @@ -365,7 +365,7 @@ environment: Then restart: ```bash -./manage.sh restart +./scripts/manage.sh restart ``` ### Permission Errors @@ -408,7 +408,7 @@ nmap -p 25565 localhost If you encounter issues: 1. Check the Troubleshooting section above -2. Review logs: `./manage.sh logs` +2. Review logs: `./scripts/manage.sh logs` 3. Check system resources: `htop` 4. Open an issue on GitHub with: - Description of the problem diff --git a/docs/LINTING.md b/docs/LINTING.md index c52f4d3..4144bb1 100644 --- a/docs/LINTING.md +++ b/docs/LINTING.md @@ -349,4 +349,4 @@ The project includes Cursor configuration in `docs/CURSOR_CONFIGURATION.md` with - [Development Guide](DEVELOPMENT.md) - Development workflow - [Testing Guide](TESTING.md) - Testing framework - [Contributing Guide](../CONTRIBUTING.md) - Contribution guidelines -- [Code Quality Standards](../AGENT_INSTRUCTIONS.md) - Code standards +- [Code Quality Standards](../AGENTS.md) - Code standards diff --git a/docs/LOG_MANAGEMENT.md b/docs/LOG_MANAGEMENT.md index 7041659..5870b1c 100644 --- a/docs/LOG_MANAGEMENT.md +++ b/docs/LOG_MANAGEMENT.md @@ -19,19 +19,19 @@ The log management system provides: **View recent logs**: ```bash -./manage.sh logs +./scripts/manage.sh logs ``` **Search logs**: ```bash -./manage.sh logs-search "player joined" +./scripts/manage.sh logs-search "player joined" ``` **Manage logs**: ```bash -./manage.sh logs-manage all +./scripts/manage.sh logs-manage all ``` ## Log Management Commands @@ -41,7 +41,7 @@ The log management system provides: Index logs for faster searching: ```bash -./manage.sh logs-manage index +./scripts/manage.sh logs-manage index ``` This will: @@ -62,7 +62,7 @@ This will: Automatically detect errors and warnings: ```bash -./manage.sh logs-manage errors +./scripts/manage.sh logs-manage errors ``` This will: @@ -84,7 +84,7 @@ This will: Rotate and archive log files: ```bash -./manage.sh logs-manage rotate +./scripts/manage.sh logs-manage rotate ``` This will: @@ -104,7 +104,7 @@ This will: View log statistics: ```bash -./manage.sh logs-manage stats +./scripts/manage.sh logs-manage stats ``` Shows: @@ -122,9 +122,9 @@ Shows: Search for any term in logs: ```bash -./manage.sh logs-search "error" -./manage.sh logs-search "player joined" -./manage.sh logs-search "crash" +./scripts/manage.sh logs-search "error" +./scripts/manage.sh logs-search "player joined" +./scripts/manage.sh logs-search "crash" ``` ### Advanced Search Options @@ -132,35 +132,35 @@ Search for any term in logs: **Case-sensitive search**: ```bash -./manage.sh logs-search -c "Error" +./scripts/manage.sh logs-search -c "Error" ``` **Limit results**: ```bash -./manage.sh logs-search -n 20 "error" +./scripts/manage.sh logs-search -n 20 "error" # Show maximum 20 results ``` **Search by log level**: ```bash -./manage.sh logs-search -l ERROR -./manage.sh logs-search -l WARN -./manage.sh logs-search -l INFO +./scripts/manage.sh logs-search -l ERROR +./scripts/manage.sh logs-search -l WARN +./scripts/manage.sh logs-search -l INFO ``` **Search by date**: ```bash -./manage.sh logs-search -d 2025-01-15 "crash" +./scripts/manage.sh logs-search -d 2025-01-15 "crash" # Search on specific date ``` **Search date range**: ```bash -./manage.sh logs-search -r 2025-01-01 2025-01-31 "player" +./scripts/manage.sh logs-search -r 2025-01-01 2025-01-31 "player" # Search entire month ``` @@ -169,25 +169,25 @@ Search for any term in logs: **Find all player connections**: ```bash -./manage.sh logs-search "joined the game" +./scripts/manage.sh logs-search "joined the game" ``` **Find all errors in last week**: ```bash -./manage.sh logs-search -r $(date -d "7 days ago" +%Y-%m-%d) $(date +%Y-%m-%d) -l ERROR +./scripts/manage.sh logs-search -r $(date -d "7 days ago" +%Y-%m-%d) $(date +%Y-%m-%d) -l ERROR ``` **Find specific player activity**: ```bash -./manage.sh logs-search "PlayerName" +./scripts/manage.sh logs-search "PlayerName" ``` **Find server crashes**: ```bash -./manage.sh logs-search "crash\|exception\|fatal" +./scripts/manage.sh logs-search "crash\|exception\|fatal" ``` ## Configuration @@ -321,7 +321,7 @@ cat config/log-management.conf | grep LOG_ROTATION **Manual rotation**: ```bash -./manage.sh logs-manage rotate +./scripts/manage.sh logs-manage rotate ``` ### Search Returns No Results @@ -329,7 +329,7 @@ cat config/log-management.conf | grep LOG_ROTATION **Re-index logs**: ```bash -./manage.sh logs-manage index +./scripts/manage.sh logs-manage index ``` **Check log files exist**: @@ -344,7 +344,7 @@ ls -lh logs/archive/ **Check log sizes**: ```bash -./manage.sh logs-manage stats +./scripts/manage.sh logs-manage stats du -sh logs/ du -sh data/logs/ ``` @@ -400,11 +400,11 @@ local error_patterns=( ```bash # Export all errors -./manage.sh logs-manage errors +./scripts/manage.sh logs-manage errors cat logs/errors_*.txt > all_errors.txt # Export specific date range -./manage.sh logs-search -r 2025-01-01 2025-01-31 "error" > january_errors.txt +./scripts/manage.sh logs-search -r 2025-01-01 2025-01-31 "error" > january_errors.txt ``` ### Log Analysis Scripts diff --git a/docs/MINECRAFT_MANAGEMENT.md b/docs/MINECRAFT_MANAGEMENT.md index 8aea982..3b1a7e3 100644 --- a/docs/MINECRAFT_MANAGEMENT.md +++ b/docs/MINECRAFT_MANAGEMENT.md @@ -306,6 +306,6 @@ The server properties manager validates all property values: - [Server Properties Guide](https://minecraft.fandom.com/wiki/Server.properties) - [Performance Tuning](RASPBERRY_PI_OPTIMIZATIONS.md) -- [API Documentation](API_DOCUMENTATION.md) +- [API Documentation](API.md) - [Quick Reference](QUICK_REFERENCE.md) diff --git a/docs/MINECRAFT_SERVER_SETUP.md b/docs/MINECRAFT_SERVER_SETUP.md index 2eff78c..675e6b5 100644 --- a/docs/MINECRAFT_SERVER_SETUP.md +++ b/docs/MINECRAFT_SERVER_SETUP.md @@ -149,7 +149,7 @@ cd ~/minecraft-server docker compose logs -f # Or use the management script -./manage.sh logs +./scripts/manage.sh logs ``` Wait for "Done!" in the logs, which means the server is ready. @@ -250,22 +250,22 @@ docker compose restart cd ~/minecraft-server # Make executable (if not already) -chmod +x manage.sh +chmod +x scripts/manage.sh # Start -./manage.sh start +./scripts/manage.sh start # Stop -./manage.sh stop +./scripts/manage.sh stop # Status -./manage.sh status +./scripts/manage.sh status # Logs -./manage.sh logs +./scripts/manage.sh logs # Console (attach to server) -./manage.sh console +./scripts/manage.sh console ``` ## Troubleshooting diff --git a/docs/MOD_SUPPORT.md b/docs/MOD_SUPPORT.md index 84cb031..aded93a 100644 --- a/docs/MOD_SUPPORT.md +++ b/docs/MOD_SUPPORT.md @@ -177,10 +177,10 @@ Install the mod pack: # In your startup script if ./scripts/mod-loader-detector.sh detect; then echo "Mod loader detected, starting modded server..." - ./manage.sh start + ./scripts/manage.sh start else echo "No mod loader detected, starting vanilla server..." - ./manage.sh start + ./scripts/manage.sh start fi ``` @@ -199,7 +199,7 @@ fi ```bash # Always backup before installing mods -./manage.sh backup +./scripts/manage.sh backup ./scripts/mod-pack-installer.sh install-url https://example.com/mod.jar ``` diff --git a/docs/MULTI_ARCHITECTURE.md b/docs/MULTI_ARCHITECTURE.md index 1ed0973..e8a07b1 100644 --- a/docs/MULTI_ARCHITECTURE.md +++ b/docs/MULTI_ARCHITECTURE.md @@ -161,8 +161,8 @@ The `openjdk:21-jdk-slim` image is multi-architecture and Docker will pull the c ```bash # Standard setup (already ARM64) -./setup-rpi.sh -./manage.sh start +./scripts/setup-rpi.sh +./scripts/manage.sh start ``` ### Raspberry Pi 4 (ARM32) @@ -174,7 +174,7 @@ docker tag minecraft-server:latest-arm32 minecraft-server:latest # Or build locally ./scripts/build-multiarch.sh arch arm32 -./manage.sh start +./scripts/manage.sh start ``` ### x86_64 Systems @@ -186,7 +186,7 @@ docker tag minecraft-server:latest-amd64 minecraft-server:latest # Or build locally ./scripts/build-multiarch.sh arch amd64 -./manage.sh start +./scripts/manage.sh start ``` ## Docker Compose Configuration @@ -215,10 +215,10 @@ services: ```bash # ARM64 -docker-compose -f docker-compose.yml -f docker-compose.arm64.yml up -d +docker compose -f docker-compose.yml -f docker-compose.arm64.yml up -d # AMD64 -docker-compose -f docker-compose.yml -f docker-compose.amd64.yml up -d +docker compose -f docker-compose.yml -f docker-compose.amd64.yml up -d ``` ## Registry Setup diff --git a/docs/MULTI_WORLD.md b/docs/MULTI_WORLD.md index 1de7967..b917485 100644 --- a/docs/MULTI_WORLD.md +++ b/docs/MULTI_WORLD.md @@ -18,26 +18,26 @@ The multi-world system allows you to: ### List Worlds ```bash -./manage.sh worlds list +./scripts/manage.sh worlds list ``` ### Create a New World ```bash # Create a normal world -./manage.sh worlds create myworld +./scripts/manage.sh worlds create myworld # Create a flat world -./manage.sh worlds create flatworld flat +./scripts/manage.sh worlds create flatworld flat # Create a world with a specific seed -./manage.sh worlds create seededworld normal 12345 +./scripts/manage.sh worlds create seededworld normal 12345 ``` ### Switch Worlds ```bash -./manage.sh worlds switch myworld +./scripts/manage.sh worlds switch myworld ``` ## World Management @@ -47,7 +47,7 @@ The multi-world system allows you to: Create a new world with specific settings: ```bash -./manage.sh worlds create [type] [seed] +./scripts/manage.sh worlds create [type] [seed] ``` **World Types**: @@ -61,13 +61,13 @@ Create a new world with specific settings: ```bash # Standard world -./manage.sh worlds create survival +./scripts/manage.sh worlds create survival # Flat world for building -./manage.sh worlds create creative flat +./scripts/manage.sh worlds create creative flat # World with seed -./manage.sh worlds create adventure normal -1234567890 +./scripts/manage.sh worlds create adventure normal -1234567890 ``` ### Listing Worlds @@ -75,7 +75,7 @@ Create a new world with specific settings: View all available worlds: ```bash -./manage.sh worlds list +./scripts/manage.sh worlds list ``` Shows: @@ -90,13 +90,13 @@ Shows: Get detailed information about a world: ```bash -./manage.sh worlds info +./scripts/manage.sh worlds info ``` Or for the current world: ```bash -./manage.sh worlds info +./scripts/manage.sh worlds info ``` ### Switching Worlds @@ -104,7 +104,7 @@ Or for the current world: Switch to a different world: ```bash -./manage.sh worlds switch +./scripts/manage.sh worlds switch ``` This will: @@ -121,7 +121,7 @@ This will: Delete a world (with automatic backup): ```bash -./manage.sh worlds delete +./scripts/manage.sh worlds delete ``` **Warning**: This permanently deletes the world. A backup is created before deletion. @@ -147,7 +147,7 @@ CREATED=2025-01-15 10:30:00 Apply world-specific settings: ```bash -./manage.sh worlds config +./scripts/manage.sh worlds config ``` This applies: @@ -171,17 +171,17 @@ When switching worlds, the system automatically: Create a template from an existing world: ```bash -./manage.sh worlds create-template [source-world] +./scripts/manage.sh worlds create-template [source-world] ``` **Example**: ```bash # Create template from current world -./manage.sh worlds create-template mytemplate +./scripts/manage.sh worlds create-template mytemplate # Create template from specific world -./manage.sh worlds create-template survival-template survival +./scripts/manage.sh worlds create-template survival-template survival ``` Templates are stored in `config/world-templates/` and can be reused to create new worlds quickly. @@ -191,13 +191,13 @@ Templates are stored in `config/world-templates/` and can be reused to create ne Create a new world from a template: ```bash -./manage.sh worlds from-template +./scripts/manage.sh worlds from-template ``` **Example**: ```bash -./manage.sh worlds from-template newworld survival-template +./scripts/manage.sh worlds from-template newworld survival-template ``` This creates a new world with the same structure as the template (excluding player data). @@ -209,13 +209,13 @@ This creates a new world with the same structure as the template (excluding play Backup a specific world: ```bash -./manage.sh worlds backup +./scripts/manage.sh worlds backup ``` Or backup the current world: ```bash -./manage.sh worlds backup +./scripts/manage.sh worlds backup ``` Backups are stored in `backups/worlds/` with timestamps. @@ -278,7 +278,7 @@ Add to crontab for automatic backups: Monitor world sizes: ```bash -./manage.sh worlds sizes +./scripts/manage.sh worlds sizes ``` Shows: @@ -300,7 +300,7 @@ Useful for: Standard Minecraft world with varied terrain: ```bash -./manage.sh worlds create myworld normal +./scripts/manage.sh worlds create myworld normal ``` ### Flat World @@ -308,7 +308,7 @@ Standard Minecraft world with varied terrain: Superflat world for building: ```bash -./manage.sh worlds create flatworld flat +./scripts/manage.sh worlds create flatworld flat ``` Configure in `server.properties`: @@ -323,7 +323,7 @@ generator-settings={"layers":[{"block":"minecraft:bedrock","height":1},{"block": Amplified terrain (requires more resources): ```bash -./manage.sh worlds create amplifiedworld amplified +./scripts/manage.sh worlds create amplifiedworld amplified ``` **Note**: Amplified worlds are resource-intensive and may not perform well on Raspberry Pi 5. @@ -333,7 +333,7 @@ Amplified terrain (requires more resources): Large biomes variant: ```bash -./manage.sh worlds create largeworld large_biomes +./scripts/manage.sh worlds create largeworld large_biomes ``` ## Best Practices @@ -352,8 +352,8 @@ Large biomes variant: **Solutions**: -1. Ensure server is stopped: `./manage.sh stop` -2. Check world exists: `./manage.sh worlds list` +1. Ensure server is stopped: `./scripts/manage.sh stop` +2. Check world exists: `./scripts/manage.sh worlds list` 3. Verify server.properties is writable 4. Check world directory has `level.dat` @@ -377,7 +377,7 @@ Large biomes variant: 1. Check disk space: `df -h` 2. Verify world directory exists 3. Check file permissions -4. Try manual backup: `./manage.sh worlds backup ` +4. Try manual backup: `./scripts/manage.sh worlds backup ` ### World Too Large @@ -385,7 +385,7 @@ Large biomes variant: **Solutions**: -1. Monitor sizes: `./manage.sh worlds sizes` +1. Monitor sizes: `./scripts/manage.sh worlds sizes` 2. Delete unused worlds 3. Use MCA Selector or similar tools to delete unused chunks 4. Consider using flat worlds for building @@ -404,17 +404,17 @@ Run multiple servers with different worlds: Move worlds between servers: -1. Backup world: `./manage.sh worlds backup ` +1. Backup world: `./scripts/manage.sh worlds backup ` 2. Copy backup file to new server 3. Extract backup: `tar -xzf world__*.tar.gz -C data/` -4. Switch to world: `./manage.sh worlds switch ` +4. Switch to world: `./scripts/manage.sh worlds switch ` ### World Cloning Clone an existing world: -1. Create template: `./manage.sh worlds create-template template ` -2. Create from template: `./manage.sh worlds from-template template` +1. Create template: `./scripts/manage.sh worlds create-template template ` +2. Create from template: `./scripts/manage.sh worlds from-template template` --- diff --git a/docs/OPTIMIZATION_COMPLETE.md b/docs/OPTIMIZATION_COMPLETE.md deleted file mode 100644 index 4a2cafc..0000000 --- a/docs/OPTIMIZATION_COMPLETE.md +++ /dev/null @@ -1,156 +0,0 @@ -# Optimization Tasks - COMPLETE ✅ - -All optimization opportunities have been successfully implemented! - -## 📋 Summary - -### Phase 1: Core Optimizations ✅ - -- ✅ React Hook Extraction (`usePolling`, `useErrorHandler`, `useAutoDismiss`) -- ✅ Component Optimizations (Dashboard, Players, Backups, Analytics, MetricsChart) -- ✅ Security Hardening (Input validation, rate limiting, security headers) - -### Phase 2: Advanced Optimizations ✅ - -- ✅ Route-Based Code Splitting (Lazy Loading) -- ✅ Debouncing & Throttling Hooks -- ✅ Virtual Scrolling Component -- ✅ API Request Caching & Deduplication -- ✅ Build Optimizations (Chunk Splitting) - -## 📊 Performance Improvements - -### Bundle Size - -- **Initial Bundle**: Reduced by ~60-70% -- **Code Splitting**: Routes loaded on-demand -- **Vendor Chunks**: Separated for better caching - -### Runtime Performance - -- **API Calls**: Reduced by ~40-50% with caching -- **Rendering**: Virtual scrolling handles large lists -- **Input Performance**: Debouncing reduces CPU usage by ~30% -- **Memory Usage**: Constant with virtual scrolling - -### User Experience - -- ✅ Faster initial page load -- ✅ Smoother interactions -- ✅ Reduced server load -- ✅ Better error handling - -## 📁 Files Created/Modified - -### New Files - -- `web/src/hooks/useDebounce.js` - Debounce hook -- `web/src/hooks/useThrottle.js` - Throttle hook -- `web/src/utils/apiCache.js` - API caching utility -- `web/src/components/VirtualList.jsx` - Virtual scrolling component -- `web/src/components/LazyRoute.jsx` - Lazy route wrapper -- `docs/ADVANCED_OPTIMIZATIONS.md` - Advanced optimizations documentation -- `docs/OPTIMIZATION_SUMMARY.md` - Optimization summary -- `docs/SECURITY_HARDENING.md` - Security documentation - -### Modified Files - -- `web/src/App.jsx` - Lazy loading for all routes -- `web/src/pages/Logs.jsx` - Debouncing + virtual scrolling -- `web/src/services/api.js` - API caching + deduplication -- `web/vite.config.js` - Build optimizations -- `web/src/pages/Dashboard.jsx` - Optimized with hooks -- `web/src/pages/Players.jsx` - Optimized with hooks -- `web/src/pages/Backups.jsx` - Optimized with hooks -- `web/src/pages/Analytics.jsx` - Optimized with hooks -- `web/src/components/MetricsChart.jsx` - Memoized - -## 🎯 Key Features - -### 1. Route-Based Code Splitting - -```jsx -const Dashboard = lazy(() => import('./pages/Dashboard')); - - - }> - - -; -``` - -### 2. API Caching Strategy - -- **Fast-changing** (status, metrics): 2-3 seconds -- **Moderate-changing** (players, backups): 5-10 seconds -- **Slow-changing** (worlds, plugins, config): 30 seconds -- **Analytics**: 60 seconds -- **Auto-invalidation**: On mutations - -### 3. Debouncing Search/Filter - -```jsx -const debouncedFilter = useDebounce(filter, 300); -const filteredLogs = useMemo( - () => logs.filter(log => log.includes(debouncedFilter)), - [logs, debouncedFilter] -); -``` - -### 4. Virtual Scrolling - -```jsx - } - itemHeight={24} - containerHeight={600} - overscan={10} -/> -``` - -## 🚀 Impact Summary - -### Developer Experience - -- ✅ Easier to add new features with reusable hooks -- ✅ Consistent patterns across components -- ✅ Less code to maintain (~200 lines saved) -- ✅ Better code organization - -### User Experience - -- ✅ Faster response times -- ✅ Smoother interactions -- ✅ More reliable data updates -- ✅ Better error messages - -### Code Quality - -- ✅ Reduced duplication (~70%) -- ✅ Better organization -- ✅ Easier to understand -- ✅ More maintainable - -## 📚 Documentation - -All optimizations are documented in: - -- `docs/OPTIMIZATION_SUMMARY.md` - Core optimizations -- `docs/ADVANCED_OPTIMIZATIONS.md` - Advanced techniques -- `docs/SECURITY_HARDENING.md` - Security improvements - -## ✨ Next Steps (Optional Future Enhancements) - -1. **Service Worker**: Offline support and advanced caching -2. **Web Workers**: Heavy computations off main thread -3. **Image Optimization**: Lazy loading and format conversion -4. **Prefetching**: Pre-load next likely routes -5. **Request Queue**: Batch multiple requests -6. **IndexedDB**: Persistent cache storage - ---- - -**Status**: ✅ ALL OPTIMIZATIONS COMPLETE -**Date**: 2025-01-27 -**Impact**: High - Significant performance improvements across all metrics diff --git a/docs/OPTIMIZATION_SUMMARY.md b/docs/OPTIMIZATION_SUMMARY.md deleted file mode 100644 index 8743615..0000000 --- a/docs/OPTIMIZATION_SUMMARY.md +++ /dev/null @@ -1,202 +0,0 @@ -# Optimization Summary - -This document summarizes all optimization tasks performed to improve performance, code quality, and maintainability. - -## ✅ Completed Optimizations - -### 1. React Hook Extraction & Code Reusability - -**Created Reusable Hooks:** - -- **`usePolling`** (`web/src/hooks/usePolling.js`) - - - Centralizes polling logic with automatic cleanup - - Provides loading, error, and data states - - Prevents memory leaks with proper cleanup - - Applied to: Dashboard, Players, Backups, Analytics - -- **`useErrorHandler`** (`web/src/hooks/useErrorHandler.js`) - - - Consistent error handling across components - - Integrates with toast notifications - - Reduces code duplication - -- **`useAutoDismiss`** (`web/src/hooks/useAutoDismiss.js`) - - Auto-dismisses messages after a delay - - Replaces repeated setTimeout patterns - - Cleaner component code - -### 2. Component Optimizations - -#### Dashboard Component - -- ✅ Replaced manual polling with `usePolling` hook -- ✅ Optimized with `useCallback` for function memoization -- ✅ Centralized error handling -- ✅ Reduced re-renders - -#### Players Component - -- ✅ Functional KICK button with confirmation -- ✅ Uses `usePolling` hook -- ✅ Proper error handling -- ✅ Loading states during operations - -#### Backups Component - -- ✅ Replaced manual polling with `usePolling` hook -- ✅ Replaced setTimeout message clearing with `useAutoDismiss` -- ✅ Removed console.error statements -- ✅ Optimized with `useCallback` -- ✅ Cleaner error handling - -#### Analytics Component - -- ✅ Replaced manual setInterval with `usePolling` hook -- ✅ Removed console.error statements -- ✅ Optimized data fetching with `useCallback` -- ✅ Better error handling - -#### MetricsChart Component - -- ✅ Added `React.memo` to prevent unnecessary re-renders -- ✅ Used `useMemo` for expensive computations -- ✅ Extracted `getStatusColor` function outside component -- ✅ Memoized data array calculation - -### 3. Performance Improvements - -**Before Optimizations:** - -- Manual polling in multiple components -- Repeated setTimeout patterns -- Unnecessary re-renders -- Console.log statements everywhere -- No memoization - -**After Optimizations:** - -- ✅ Centralized polling with automatic cleanup -- ✅ Reusable hooks reduce code duplication -- ✅ Memoized expensive components -- ✅ Reduced unnecessary re-renders -- ✅ Cleaner, more maintainable code - -### 4. Code Quality Improvements - -- ✅ Removed ~50+ lines of duplicate code -- ✅ Standardized error handling patterns -- ✅ Consistent loading states -- ✅ Better component organization -- ✅ Improved code readability - -## 📊 Performance Metrics - -### Code Reduction - -- **Lines Saved**: ~150-200 lines by extracting common patterns -- **Components Optimized**: 5 major components -- **Hooks Created**: 3 reusable hooks -- **Duplicate Code**: Reduced by ~70% - -### Runtime Performance - -- **Re-render Reduction**: ~30-40% fewer unnecessary re-renders -- **Memory Leaks Prevented**: Automatic cleanup in all hooks -- **Network Efficiency**: Consistent polling intervals, no duplicate requests - -### Bundle Size - -- **Impact**: Minimal (hooks are small utilities) -- **Tree Shaking**: Enabled by default in Vite -- **Code Splitting**: Ready for lazy loading implementation - -## 🔄 Remaining Optimization Opportunities - -### High Priority - -1. **Apply usePolling to More Components** - - - Worlds.jsx - Currently no polling - - Plugins.jsx - Could benefit from polling - - FileBrowser.jsx - Static but could refresh periodically - -2. **Route-based Code Splitting** - - - Implement React.lazy() for route components - - Reduce initial bundle size - - Faster initial page load - -3. **Search/Filter Debouncing** - - Add debouncing to Logs filter - - Add debouncing to search inputs - - Reduce unnecessary API calls - -### Medium Priority - -4. **Virtual Scrolling** - - - For long lists (backups, logs, players) - - Improve rendering performance - - Better memory usage - -5. **Request Deduplication** - - - Prevent duplicate API calls - - Cache responses for short periods - - Reduce server load - -6. **Image Optimization** - - Lazy load images - - Optimize image formats - - Use WebP where supported - -### Low Priority - -7. **Service Worker for Offline Support** - - - Cache API responses - - Offline functionality - - Background sync - -8. **Web Workers for Heavy Computations** - - Analytics calculations - - Log parsing - - Data processing - -## 📝 Best Practices Established - -1. **Always use hooks for polling** - Never manual setInterval -2. **Memoize expensive components** - Use React.memo and useMemo -3. **Use useCallback for event handlers** - Prevent unnecessary re-renders -4. **Extract common patterns to hooks** - Don't repeat yourself -5. **Centralize error handling** - Use useErrorHandler hook -6. **Auto-dismiss messages** - Use useAutoDismiss hook - -## 🎯 Impact Summary - -### Developer Experience - -- ✅ Easier to add new features with reusable hooks -- ✅ Consistent patterns across components -- ✅ Less code to maintain -- ✅ Better testing (hooks can be tested independently) - -### User Experience - -- ✅ Faster response times -- ✅ Smoother interactions -- ✅ More reliable data updates -- ✅ Better error messages - -### Code Quality - -- ✅ Reduced duplication -- ✅ Better organization -- ✅ Easier to understand -- ✅ More maintainable - ---- - -**Last Updated**: 2025-01-27 -**Status**: ✅ Core optimizations complete diff --git a/docs/PERFORMANCE_BENCHMARKING.md b/docs/PERFORMANCE_BENCHMARKING.md index 2bfc8df..67e397c 100644 --- a/docs/PERFORMANCE_BENCHMARKING.md +++ b/docs/PERFORMANCE_BENCHMARKING.md @@ -53,7 +53,7 @@ Measures the time from server start command to server ready state. **Measurement**: -- Time from `docker-compose up` to server logs showing "Done" +- Time from `docker compose up` to server logs showing "Done" - Includes container startup, JVM initialization, and world loading ### TPS (Ticks Per Second) diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md index f894555..aeccf20 100644 --- a/docs/QUICK_REFERENCE.md +++ b/docs/QUICK_REFERENCE.md @@ -5,14 +5,14 @@ ### Server Management ```bash -./manage.sh start # Start server -./manage.sh stop # Stop server -./manage.sh restart # Restart server -./manage.sh status # Check status -./manage.sh logs # View logs -./manage.sh backup # Create backup (with world save & verification) -./manage.sh console # Attach to server console -./manage.sh update # Update configuration from git +./scripts/manage.sh start # Start server +./scripts/manage.sh stop # Stop server +./scripts/manage.sh restart # Restart server +./scripts/manage.sh status # Check status +./scripts/manage.sh logs # View logs +./scripts/manage.sh backup # Create backup (with world save & verification) +./scripts/manage.sh console # Attach to server console +./scripts/manage.sh update # Update configuration from git ``` ### Backup Management @@ -35,11 +35,11 @@ ### Docker Commands ```bash -docker-compose up -d # Start in background -docker-compose down # Stop and remove -docker-compose ps # List containers -docker-compose logs -f # Follow logs -docker-compose restart # Restart services +docker compose up -d # Start in background +docker compose down # Stop and remove +docker compose ps # List containers +docker compose logs -f # Follow logs +docker compose restart # Restart services docker attach minecraft-server # Attach to console ``` @@ -173,16 +173,16 @@ nmap -p 25565 localhost ### Create Backup ```bash -./manage.sh backup +./scripts/manage.sh backup # Stored in: ./backups/minecraft_backup_TIMESTAMP.tar.gz ``` ### Restore Backup ```bash -./manage.sh stop +./scripts/manage.sh stop tar -xzf backups/minecraft_backup_YYYYMMDD_HHMMSS.tar.gz -C ./data/ -./manage.sh start +./scripts/manage.sh start ``` ### Automated Backups (Cron) @@ -190,7 +190,7 @@ tar -xzf backups/minecraft_backup_YYYYMMDD_HHMMSS.tar.gz -C ./data/ ```bash crontab -e # Add line for daily backup at 3 AM: -0 3 * * * cd ~/minecraft-server && ./manage.sh backup +0 3 * * * cd ~/minecraft-server && ./scripts/manage.sh backup ``` ## Troubleshooting Quick Fixes @@ -199,8 +199,8 @@ crontab -e ```bash sudo systemctl restart docker -docker-compose down -docker-compose up -d +docker compose down +docker compose up -d ``` ### High Memory Usage @@ -209,14 +209,14 @@ docker-compose up -d # Reduce memory in docker-compose.yml # Reduce view-distance in server.properties # Restart server -./manage.sh restart +./scripts/manage.sh restart ``` ### Connection Refused ```bash # Check if server is running -./manage.sh status +./scripts/manage.sh status # Check if port is open sudo ufw allow 25565/tcp @@ -245,7 +245,7 @@ docker system prune -a ```bash cd ~/minecraft-server git pull -./manage.sh restart +./scripts/manage.sh restart ``` ### Update Minecraft Version @@ -256,9 +256,9 @@ nano docker-compose.yml # Change MINECRAFT_VERSION # Rebuild and restart -docker-compose down +docker compose down rm -rf data/*.jar # Remove old jar -docker-compose up -d --build +docker compose up -d --build ``` ### Update Raspberry Pi OS @@ -297,7 +297,7 @@ sudo ufw enable htop # Terminal 2: Server logs -cd ~/minecraft-server && ./manage.sh logs +cd ~/minecraft-server && ./scripts/manage.sh logs # Terminal 3: Docker stats docker stats minecraft-server @@ -317,11 +317,11 @@ docker ps --filter "name=minecraft-server" --format "{{.Status}}" | Problem | Solution | | --------------------------- | --------------------------------------------------- | -| Can't connect locally | Check if server is running: `./manage.sh status` | +| Can't connect locally | Check if server is running: `./scripts/manage.sh status` | | Can't connect from internet | Configure port forwarding on router | | Low FPS/lag | Reduce view-distance and max-players | | Out of memory | Lower MEMORY_MAX in docker-compose.yml | -| Server crash on startup | Check logs: `./manage.sh logs` | +| Server crash on startup | Check logs: `./scripts/manage.sh logs` | | Permission denied | Run: `sudo chown -R $USER:$USER ~/minecraft-server` | ## Contact & Support @@ -337,9 +337,9 @@ docker ps --filter "name=minecraft-server" --format "{{.Status}}" 1. Flash Raspberry Pi OS with Imager 2. SSH to Pi: `ssh pi@minecraft-server.local` 3. Clone repo: `git clone https://github.com/and3rn3t/minecraft.git minecraft-server` -4. Run setup: `cd minecraft-server && ./setup-rpi.sh` +4. Run setup: `cd minecraft-server && ./scripts/setup-rpi.sh` 5. Log out and back in -6. Start server: `./manage.sh start` +6. Start server: `./scripts/manage.sh start` 7. Connect: `minecraft-server.local:25565` -**Emergency Stop:** `./manage.sh stop` or `docker-compose down` +**Emergency Stop:** `./scripts/manage.sh stop` or `docker compose down` diff --git a/docs/RASPBERRY_PI_COMPATIBILITY.md b/docs/RASPBERRY_PI_COMPATIBILITY.md index e718eac..66451f0 100644 --- a/docs/RASPBERRY_PI_COMPATIBILITY.md +++ b/docs/RASPBERRY_PI_COMPATIBILITY.md @@ -76,7 +76,7 @@ When building on Raspberry Pi 5: ```bash # Build directly on Pi (recommended) -docker-compose build +docker compose build # Or specify platform explicitly docker buildx build --platform linux/arm64 -t minecraft-server . @@ -150,7 +150,7 @@ chmod +x scripts/setup-rpi.sh ./scripts/setup-rpi.sh # 3. Build Docker image -docker-compose build +docker compose build # 4. Start server ./scripts/manage.sh start @@ -168,7 +168,7 @@ docker buildx create --name multiarch --use docker buildx build --platform linux/arm64 -t minecraft-server:arm64 . # Or with docker-compose -docker-compose build --build-arg BUILDPLATFORM=linux/arm64 +docker compose build --build-arg BUILDPLATFORM=linux/arm64 ``` **Action Required**: ⚠️ Document cross-platform building (optional) @@ -195,7 +195,7 @@ Before deploying to Raspberry Pi 5: - [ ] **Docker Ready**: - [ ] Docker installed: `docker --version` - - [ ] Docker Compose installed: `docker-compose --version` + - [ ] Docker Compose installed: `docker compose --version` - [ ] User in docker group: `groups | grep docker` ### Deployment Testing @@ -220,7 +220,7 @@ Before deploying to Raspberry Pi 5: 3. **Build Docker Image**: ```bash - docker-compose build + docker compose build # Should complete without errors ``` @@ -258,7 +258,7 @@ python3 -m pytest tests/api/ -v bash -n scripts/*.sh # Docker Compose validation -docker-compose config +docker compose config ``` ## Performance Considerations @@ -306,7 +306,7 @@ Raspberry Pi 5 has 4 cores. Optimize JVM flags in `scripts/start.sh`: #### 1. Docker Build Fails -**Symptoms**: `docker-compose build` fails with architecture errors +**Symptoms**: `docker compose build` fails with architecture errors **Solutions**: @@ -362,7 +362,7 @@ npm install ```bash # Check logs -docker-compose logs +docker compose logs # Check architecture compatibility docker inspect minecraft-server | grep Architecture diff --git a/docs/RASPBERRY_PI_OPTIMIZATIONS.md b/docs/RASPBERRY_PI_OPTIMIZATIONS.md index 0c56bc3..9ec4ed1 100644 --- a/docs/RASPBERRY_PI_OPTIMIZATIONS.md +++ b/docs/RASPBERRY_PI_OPTIMIZATIONS.md @@ -356,10 +356,10 @@ Use Docker build cache effectively: ```bash # Build with cache -docker-compose build --parallel +docker compose build --parallel # Or use BuildKit -DOCKER_BUILDKIT=1 docker-compose build +DOCKER_BUILDKIT=1 docker compose build ``` ### Parallel Builds diff --git a/docs/RBAC.md b/docs/RBAC.md index b7dce1a..c9060bc 100644 --- a/docs/RBAC.md +++ b/docs/RBAC.md @@ -362,4 +362,4 @@ const admins = users.filter(u => u.role === 'admin'); - [API Documentation](API.md) - Complete API reference - [Web Interface Guide](WEB_INTERFACE.md) - Web UI documentation -- [Security Guide](SECURITY.md) - Security best practices +- [Security Hardening](SECURITY_HARDENING.md) - Security best practices diff --git a/docs/README.md b/docs/README.md index f6a7297..facd400 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,94 +1,14 @@ -# Documentation Directory +# Documentation -This directory contains all project documentation organized by category. +**[INDEX.md](INDEX.md) is the navigation hub** — every guide in this project is +listed there, grouped by task. -## 📚 Documentation Index +Quick jumps: -**Start here**: [INDEX.md](INDEX.md) - Complete navigation guide to all documentation +- Installing for the first time → [INSTALL.md](INSTALL.md) +- Looking up a command → [QUICK_REFERENCE.md](QUICK_REFERENCE.md) +- Something is broken → [TROUBLESHOOTING.md](TROUBLESHOOTING.md) +- Working on the code → [DEVELOPMENT.md](DEVELOPMENT.md) and [../AGENTS.md](../AGENTS.md) -## Structure - -``` -docs/ -├── INDEX.md # Navigation hub - start here! -│ -├── Getting Started/ -│ ├── INSTALL.md # Installation guide -│ └── QUICK_REFERENCE.md # Command reference -│ -├── User Guides/ -│ ├── BACKUP_AND_MONITORING.md -│ ├── UPDATE_MANAGEMENT.md -│ ├── PLUGIN_MANAGEMENT.md -│ ├── MULTI_WORLD.md -│ ├── LOG_MANAGEMENT.md -│ ├── RCON.md -│ ├── API.md # Complete REST API guide -│ ├── WEB_INTERFACE.md -│ ├── RBAC.md -│ ├── API_KEYS.md -│ └── DYNAMIC_DNS.md -│ -├── Developer Guides/ -│ ├── DEVELOPMENT.md -│ ├── TESTING.md # Complete testing guide -│ ├── CI_CD.md # Complete CI/CD guide -│ ├── ROADMAP.md -│ ├── CURSOR_CONFIGURATION.md -│ └── WORKSPACE_ENHANCEMENTS.md -│ -├── Reference/ -│ ├── CONFIGURATION_EXAMPLES.md -│ ├── TROUBLESHOOTING.md -│ ├── TEST_COVERAGE.md -│ └── WEB_UI_TESTING.md -│ -└── archive/ # Archived/superseded docs - └── README.md # Archive index -``` - -## Quick Access - -### For Users - -- **New to the project?** → [INSTALL.md](INSTALL.md) -- **Need a command?** → [QUICK_REFERENCE.md](QUICK_REFERENCE.md) -- **Having problems?** → [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - -### For Developers - -- **Setting up dev environment?** → [DEVELOPMENT.md](DEVELOPMENT.md) -- **Want to contribute?** → [../CONTRIBUTING.md](../CONTRIBUTING.md) -- **Setting up Cursor IDE?** → [CURSOR_CONFIGURATION.md](CURSOR_CONFIGURATION.md) - -### For Planning - -- **What's next?** → [ROADMAP.md](ROADMAP.md) -- **What needs doing?** → [TASKS.md](TASKS.md) -- **What changed?** → [../CHANGELOG.md](../CHANGELOG.md) - -## Documentation Standards - -All documentation follows these standards: - -- Markdown format -- Clear headings and structure -- Code examples included -- Links kept relative -- Updated when features change - -## Contributing to Documentation - -When adding or updating documentation: - -1. Update [INDEX.md](INDEX.md) if adding new docs -2. Follow existing documentation style -3. Include code examples -4. Update related documentation -5. Update [CHANGELOG.md](../CHANGELOG.md) if user-facing - -## See Also - -- [Main README](../README.md) - Project overview -- [Agent Instructions](../AGENT_INSTRUCTIONS.md) - AI agent guide -- [Contributing Guide](../CONTRIBUTING.md) - How to contribute +Adding a document? Put it in this directory and add a row to the matching table in +[INDEX.md](INDEX.md), or nobody will find it. diff --git a/docs/RESTART_LOOP_TROUBLESHOOTING.md b/docs/RESTART_LOOP_TROUBLESHOOTING.md deleted file mode 100644 index 82c253e..0000000 --- a/docs/RESTART_LOOP_TROUBLESHOOTING.md +++ /dev/null @@ -1,251 +0,0 @@ -# Server Restart Loop Troubleshooting - -If your Minecraft server keeps restarting, follow these steps to diagnose and fix the issue. - -## Quick Diagnosis - -1. **Check container status**: - - ```bash - docker ps -a | grep minecraft-server - ``` - -2. **View recent logs**: - - ```bash - docker logs --tail 100 minecraft-server - ``` - -3. **Check restart count**: - - ```bash - docker inspect minecraft-server | grep -A 5 RestartCount - ``` - -## Common Causes - -### 1. Out of Memory (OOM) - -**Symptoms**: Logs show `OutOfMemoryError` or container is killed by Docker - -**Solution**: - -- Reduce memory allocation in `docker-compose.yml`: - - ```yaml - environment: - - MEMORY_MIN=512M - - MEMORY_MAX=1G - ``` - -- Check system memory: - - ```bash - free -h - ``` - -### 2. Server JAR Missing or Corrupted - -**Symptoms**: "Could not find or load main class" or "Error: Unable to access jarfile" - -**Solution**: - -```bash -# Stop server -docker-compose down - -# Check if server.jar exists -ls -lh data/server.jar - -# If missing, the start script will download it on next start -# Or manually download: -cd data -wget -O server.jar https://piston-data.mojang.com/v1/objects/8dd1a28015f51b1803213892b50b7b4fc76e594d/server.jar -``` - -### 3. Port Already in Use - -**Symptoms**: "Address already in use" in logs - -**Solution**: - -```bash -# Find what's using port 25565 -sudo netstat -tlnp | grep 25565 -# or -sudo lsof -i :25565 - -# Kill the process or change port in docker-compose.yml -``` - -### 4. Corrupted World Data - -**Symptoms**: Server crashes during world loading - -**Solution**: - -```bash -# Stop server -docker-compose down - -# Backup and remove corrupted world -mv data/world data/world.backup.$(date +%Y%m%d) -# Or delete if you don't need it: -# rm -rf data/world - -# Restart -docker-compose up -d -``` - -### 5. Healthcheck Failing - -**Symptoms**: Container restarts even though Java is running - -**Solution**: - -- Increase healthcheck start period in `docker-compose.yml`: - - ```yaml - healthcheck: - start_period: 180s # Give server more time to start - retries: 5 - ``` - -### 6. Disk Space Full - -**Symptoms**: "No space left on device" in logs - -**Solution**: - -```bash -# Check disk space -df -h - -# Clean up old backups/logs -./scripts/log-manager.sh clean -# Or manually: -rm -rf backups/*.tar.gz -rm -rf data/logs/*.log.gz -``` - -### 7. Insufficient Permissions - -**Symptoms**: Permission denied errors in logs - -**Solution**: - -```bash -# Fix permissions -sudo chown -R $USER:$USER data/ backups/ plugins/ -chmod -R 755 data/ backups/ plugins/ -``` - -## Temporary Fix: Disable Auto-Restart - -To stop the restart loop temporarily and investigate: - -1. **Change restart policy**: - - ```yaml - # In docker-compose.yml, change: - restart: on-failure - # to: - restart: "no" - ``` - -2. **Restart container**: - - ```bash - docker-compose up -d - ``` - -3. **Monitor logs**: - - ```bash - docker logs -f minecraft-server - ``` - -4. **Once fixed, restore restart policy**: - - ```yaml - restart: on-failure - ``` - -## Advanced Debugging - -### Enable Verbose Logging - -Add to `docker-compose.yml`: - -```yaml -environment: - - JAVA_OPTS=-Xlog:gc*:file=/minecraft/server/logs/gc.log -XX:+PrintGCDetails -``` - -### Check System Resources - -```bash -# CPU and Memory usage -docker stats minecraft-server - -# System temperature (Raspberry Pi) -vcgencmd measure_temp -vcgencmd get_throttled - -# Disk I/O -iostat -x 1 -``` - -### Check Java Process - -```bash -# Inside container -docker exec minecraft-server ps aux | grep java -docker exec minecraft-server pgrep -f java - -# Check Java version -docker exec minecraft-server java -version -``` - -## Prevention - -1. **Monitor logs regularly**: - - ```bash - docker logs --tail 50 -f minecraft-server - ``` - -2. **Set appropriate memory limits** for your system - -3. **Enable log rotation** to prevent disk fill - -4. **Regular backups** before making changes - -5. **Test changes** in a separate environment first - -## Getting Help - -If the issue persists, collect this information: - -```bash -# System info -uname -a -free -h -df -h - -# Docker info -docker version -docker-compose version - -# Server logs (last 200 lines) -docker logs --tail 200 minecraft-server > server-logs.txt - -# Container inspect -docker inspect minecraft-server > container-info.json - -# Server configuration -cat docker-compose.yml -cat data/server.properties | head -20 -``` - -Share these files when asking for help. diff --git a/docs/SETUP_CHECKLIST.md b/docs/SETUP_CHECKLIST.md deleted file mode 100644 index ad15e64..0000000 --- a/docs/SETUP_CHECKLIST.md +++ /dev/null @@ -1,313 +0,0 @@ -# Minecraft Server Setup Checklist - -Use this checklist to ensure your server is fully configured and ready to use. - -## ✅ Completed Setup - -- [x] Docker installed and working -- [x] Docker Compose plugin configured -- [x] Minecraft server container running -- [x] Systemd service configured for auto-start -- [x] API server running and accessible -- [x] Web frontend running and accessible -- [x] API key created -- [x] Network access configured - -## 🔧 Recommended Configuration - -### 1. Server Properties Configuration - -Configure your server settings: - -```bash -cd ~/minecraft-server - -# Edit server properties -nano data/server.properties -``` - -**Key settings to configure:** - -```properties -# Server Name -motd=My Minecraft Server - -# Player Limits -max-players=10 - -# Game Settings -difficulty=normal -gamemode=survival -pvp=true - -# Performance (adjust for your Pi) -view-distance=10 # Lower = better performance (6-12) -simulation-distance=8 # Lower = better performance (4-10) - -# Security -white-list=false # Set to true to enable whitelist -online-mode=true # Require Minecraft authentication -spawn-protection=16 # Protected spawn radius - -# World Settings -level-name=world -level-seed= # Leave empty for random -generate-structures=true -``` - -**After editing, restart:** - -```bash -sudo systemctl restart minecraft.service -``` - -### 2. Memory Settings (Optimize for Your Pi) - -Check your Pi's RAM: - -```bash -free -h -``` - -**For 4GB Pi:** - -```bash -cd ~/minecraft-server -nano docker-compose.yml -``` - -Change to: - -```yaml -environment: - - MEMORY_MIN=1G - - MEMORY_MAX=2G -``` - -**For 8GB Pi:** - -```yaml -environment: - - MEMORY_MIN=2G - - MEMORY_MAX=4G -``` - -Then restart: - -```bash -cd ~/minecraft-server -docker compose down -docker compose up -d -``` - -### 3. Test Minecraft Server Connection - -**From your local network:** - -1. Open Minecraft -2. Multiplayer → Add Server -3. Server Address: `192.168.1.22:25565` (your Pi's IP) -4. Click Done and join - -**Verify server is accessible:** - -```bash -# Check if port is listening -sudo netstat -tulpn | grep 25565 - -# Check server logs -cd ~/minecraft-server -docker compose logs --tail 50 -``` - -### 4. Port Forwarding (For External Access) - -To allow players outside your network: - -1. **Log into your router** (usually 192.168.1.1) -2. **Find Port Forwarding settings** -3. **Add rule:** - - External Port: 25565 - - Internal Port: 25565 - - Internal IP: 192.168.1.22 (your Pi's IP) - - Protocol: TCP -4. **Save and apply** - -**Find your public IP:** - -```bash -curl ifconfig.me -``` - -Share this IP with friends: `YOUR_PUBLIC_IP:25565` - -### 5. Configure Automatic Backups - -Set up automated backups: - -```bash -cd ~/minecraft-server - -# Create backup schedule config -nano config/backup-schedule.conf -``` - -Add: - -``` -SCHEDULE=daily -TIME=03:00 -ENABLED=true -``` - -**Or use the backup script:** - -```bash -# Manual backup -./manage.sh backup - -# Install automated backup timer -./scripts/install-backup-timer.sh -``` - -### 6. Firewall Configuration - -Ensure ports are open: - -```bash -# Allow Minecraft port -sudo ufw allow 25565/tcp - -# Allow API port (already done) -sudo ufw allow 8080/tcp - -# Allow web frontend port (already done) -sudo ufw allow 5173/tcp - -# Check status -sudo ufw status -``` - -### 7. Optional: Install Plugins (Paper/Spigot) - -If you want plugins, switch to Paper: - -```bash -cd ~/minecraft-server - -# Switch to Paper server -./scripts/switch-server-type.sh paper - -# Restart server -sudo systemctl restart minecraft.service - -# Install plugins -./scripts/plugin-manager.sh install /path/to/plugin.jar -``` - -### 8. Optional: Configure RCON (Remote Console) - -Enable RCON for remote server management: - -```bash -cd ~/minecraft-server - -# Setup RCON -./scripts/rcon-setup.sh - -# Test RCON connection -./scripts/rcon-client.sh "list" -``` - -### 9. Server Optimization - -**For better performance on Raspberry Pi 5:** - -```bash -cd ~/minecraft-server - -# Run optimization script -./scripts/optimize-rpi5.sh - -# Or manually optimize -./scripts/performance-presets.sh balanced -``` - -### 10. Test Everything - -**Complete system test:** - -```bash -cd ~/minecraft-server - -# 1. Check Minecraft server -docker ps | grep minecraft -docker compose logs --tail 20 - -# 2. Check API server -./scripts/api-server.sh status -curl -H "X-API-Key: YOUR_KEY" http://localhost:8080/api/status - -# 3. Check web frontend -curl http://localhost:5173 - -# 4. Test Minecraft connection -# From another computer, try connecting to 192.168.1.22:25565 -``` - -## 📋 Quick Configuration Summary - -**Essential settings to check:** - -1. ✅ Server name (motd in server.properties) -2. ✅ Max players (max-players) -3. ✅ Difficulty (difficulty) -4. ✅ Memory limits (docker-compose.yml) -5. ✅ View distance (view-distance in server.properties) -6. ✅ Port forwarding (router settings) -7. ✅ Firewall rules (ufw) - -## 🎮 Ready to Play! - -Once you've completed the checklist: - -1. **Local Network**: Players can connect using `192.168.1.22:25565` -2. **External Network**: Players can connect using `YOUR_PUBLIC_IP:25565` (after port forwarding) -3. **Web Interface**: Access at `http://192.168.1.22:5173` -4. **API**: Available at `http://192.168.1.22:8080/api` - -## 🔍 Troubleshooting - -**Server won't start:** - -```bash -docker compose logs -sudo systemctl status minecraft.service -``` - -**Can't connect:** - -```bash -# Check if server is running -docker ps - -# Check if port is open -sudo netstat -tulpn | grep 25565 - -# Check firewall -sudo ufw status -``` - -**Performance issues:** - -- Lower view-distance in server.properties -- Reduce max-players -- Check memory usage: `free -h` -- Monitor server: `docker stats minecraft-server` - -## 📚 Additional Resources - -- [Server Properties Guide](https://minecraft.fandom.com/wiki/Server.properties) -- [Performance Optimization](docs/RASPBERRY_PI_OPTIMIZATIONS.md) -- [Backup Management](docs/BACKUP_AND_MONITORING.md) -- [Plugin Management](docs/PLUGIN_MANAGEMENT.md) diff --git a/docs/TESTING.md b/docs/TESTING.md index b91673d..9d9a157 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -238,48 +238,33 @@ See `.github/workflows/tests.yml` for configuration. ## Test Coverage -### Current Coverage +Coverage is measured for the Python API with `coverage.py`, configured in +`.coverage-config.ini`. The enforced threshold is **40%** (`fail_under`); raise it +in that file as coverage grows. `scripts/check-coverage.sh` honours the same value +via `COVERAGE_THRESHOLD`. -- **API Endpoints**: 51% coverage -- **Authentication**: ✅ Fully tested -- **Error Handling**: ✅ Fully tested -- **Health Checks**: ✅ Fully tested +### Running coverage -### Coverage Goals - -- **Target**: 80%+ coverage for API -- **Current**: ~60%+ coverage (increased from 51%) -- **Priority**: Critical paths first -- **Focus**: Authentication, error handling, core endpoints, configuration management - -### New Test Coverage (This Session) - -**Backend API Tests:** - -- Configuration file management endpoints (list, get, save, validate) -- Backup restore and delete endpoints -- User authentication endpoints (register, login, logout, me) -- OAuth endpoints (get URL, link, unlink) - -**Frontend Component Tests:** +```bash +make coverage # pytest with term + HTML report +make coverage-check # fail if below the threshold +make coverage-gaps # list untested lines by file +``` -- ConfigEditor component (rendering, editing, saving, error handling) -- OAuthButtons component (Google/Apple buttons, popup handling, callbacks) -- AuthContext (authentication state, login, register, logout) -- Login page (form rendering, validation, error handling) -- Register page (form rendering, password validation, error handling) -- ConfigFiles page (file list, loading, error handling) +Reports land in `htmlcov/` (open `htmlcov/index.html`), plus `coverage.json` and +`coverage.xml` for tooling. CI publishes the same numbers on every run — treat +that as the source of truth rather than any figure written into a document. -### Viewing Coverage +### What is covered -```bash -# Terminal report -python -m pytest tests/api/ --cov=api --cov-report=term-missing +- **Well covered**: authentication and API keys, RBAC, OAuth, backup management, + config-file endpoints, analytics endpoints, log streaming, `run_script`. +- **Partially covered**: server control workflows, monitoring/metrics integration, + error and failure paths. +- **Thin**: shell-script unit tests (`tests/unit/` covers only a few scripts) and + end-to-end workflows, several of which skip without a live server. -# HTML report -python -m pytest tests/api/ --cov=api --cov-report=html -open htmlcov/index.html -``` +Open gaps worth closing are tracked in [TASKS.md](TASKS.md) rather than duplicated here. ## Continuous Improvement @@ -485,7 +470,6 @@ pytest -m "not slow" - [pytest Documentation](https://docs.pytest.org/) - [BATS Documentation](https://bats-core.readthedocs.io/) -- [Test Coverage Guide](TEST_COVERAGE.md) - Detailed coverage analysis - [Web UI Testing Guide](WEB_UI_TESTING.md) - Frontend testing guide - [Coverage.py Documentation](https://coverage.readthedocs.io/) - [pytest-xdist Documentation](https://pytest-xdist.readthedocs.io/) diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md deleted file mode 100644 index 6e91aaa..0000000 --- a/docs/TEST_COVERAGE.md +++ /dev/null @@ -1,320 +0,0 @@ -# Test Coverage Guide - -This document outlines the test coverage for the Minecraft Server Management project and identifies areas that need additional testing. - -## Current Test Coverage - -### ✅ Well Covered Areas - -1. **Authentication & Authorization** - - - User registration and login (`test_auth.py`) - - API key management (`test_api.py`) - - RBAC permissions (`test_rbac.py`) - - OAuth integration (`test_oauth.py`) - -2. **Backup Management** - - - Backup creation and listing (`test_backup_management.py`) - - Integration tests (`test-backup-system.sh`) - -3. **Configuration Files** - - File retrieval and saving (`test_config_files.py`) - -### ⚠️ Partially Covered Areas - -1. **API Endpoints** - - - Most endpoints only test authentication requirements - - Limited functional testing - - Missing error handling tests - -2. **Server Control** - - - Basic start/stop/restart tests - - Missing comprehensive workflow tests - -3. **Monitoring & Metrics** - - Basic metrics endpoint tests - - Missing integration with actual monitoring - -### ❌ Missing Coverage - -1. **Analytics System** (NEW - Just Added) - - - ✅ Analytics API endpoint tests (`test_analytics.py`) - - ✅ Integration tests (`test-analytics.sh`) - - ✅ E2E tests (`test-analytics-workflow.sh`) - - ✅ Unit tests for collector (`test-analytics-collector.sh`) - - ⚠️ Unit tests for processor (Python script) - -2. **End-to-End Workflows** - - - Most E2E tests are skipped/placeholder - - Missing complete user journey tests - -3. **Web UI Components** - - - No React component tests - - No UI integration tests - -4. **Script Unit Tests** - - - Missing tests for many management scripts - - Limited coverage for error cases - -5. **Error Handling** - - Limited edge case testing - - Missing failure scenario tests - -## New Tests Added - -### Analytics Tests - -#### API Tests (`tests/api/test_analytics.py`) - -- ✅ Analytics collection endpoint -- ✅ Report generation endpoint -- ✅ Trends endpoint -- ✅ Anomalies endpoint -- ✅ Predictions endpoint -- ✅ Player behavior endpoint -- ✅ Custom report generation - -#### Integration Tests (`tests/integration/test-analytics.sh`) - -- ✅ Data collection workflow -- ✅ Report generation -- ✅ Anomaly detection -- ✅ Data retention -- ✅ End-to-end analytics workflow - -#### E2E Tests (`tests/e2e/test-analytics-workflow.sh`) - -- ✅ Complete API workflow -- ✅ Data collection via API -- ✅ Report retrieval via API -- ✅ All analytics endpoints - -#### Unit Tests (`tests/unit/test-analytics-collector.sh`) - -- ✅ Script execution -- ✅ File creation -- ✅ JSON validation -- ✅ Error handling - -### Comprehensive API Tests (`tests/api/test_api_comprehensive.py`) - -- ✅ Server control functional tests -- ✅ Backup management functional tests -- ✅ Metrics data retrieval -- ✅ Config file operations -- ✅ Error handling -- ✅ Query parameter handling - -## Recommended Additional Tests - -### High Priority - -1. **Analytics Processor Unit Tests** - - ```python - # tests/api/test_analytics_processor.py - - Test trend calculation - - Test anomaly detection algorithms - - Test prediction algorithms - - Test data loading and filtering - ``` - -2. **Web UI Component Tests** - - ```javascript - // web/src/pages/__tests__/Analytics.test.jsx - - Component rendering - - Data fetching - - User interactions - - Error states - ``` - -3. **Complete E2E Workflows** - - ```bash - # tests/e2e/test-complete-user-journey.sh - - User registration → Login → Server management - - Backup creation → Restore workflow - - Analytics collection → Report generation → View dashboard - ``` - -4. **Error Handling Tests** - ```python - # tests/api/test_error_handling.py - - Network failures - - File system errors - - Invalid input handling - - Timeout scenarios - ``` - -### Medium Priority - -5. **Script Unit Tests** - - ```bash - # tests/unit/test-plugin-manager.sh - # tests/unit/test-world-manager.sh - # tests/unit/test-backup-scheduler.sh - - Script execution - - Parameter validation - - Error handling - - Output validation - ``` - -6. **Performance Tests** - - ```python - # tests/performance/test_api_performance.py - - Response time benchmarks - - Concurrent request handling - - Memory usage under load - ``` - -7. **Security Tests** - ```python - # tests/security/test_security.py - - SQL injection prevention - - XSS prevention - - CSRF protection - - Authentication bypass attempts - ``` - -### Low Priority - -8. **Load Tests** - - ```python - # tests/load/test_load.py - - High concurrent user scenarios - - Large data set handling - - Resource exhaustion scenarios - ``` - -9. **Compatibility Tests** - ```bash - # tests/compatibility/test_versions.sh - - Different Python versions - - Different Docker versions - - Different OS versions - ``` - -## Running Tests - -### All Tests - -```bash -./scripts/run-tests.sh -``` - -### Specific Test Suites - -```bash -# Analytics tests -pytest tests/api/test_analytics.py -v - -# Integration tests -bats tests/integration/test-analytics.sh - -# E2E tests -bats tests/e2e/test-analytics-workflow.sh - -# Unit tests -bats tests/unit/test-analytics-collector.sh -``` - -### With Coverage - -```bash -# Python tests with coverage -pytest tests/api/ --cov=api --cov-report=html - -# Check coverage threshold -./scripts/check-coverage.sh check -``` - -## Coverage Goals - -### Current Status - -- **API Coverage**: ~60% (target: 70%+) -- **Script Coverage**: ~40% (target: 60%+) -- **E2E Coverage**: ~20% (target: 50%+) -- **Overall Coverage**: ~51% (target: 60%+) - -### Priority Areas for Improvement - -1. **Analytics System**: 0% → 80%+ ✅ (Just completed) -2. **API Endpoints**: 40% → 70%+ (In progress) -3. **E2E Workflows**: 20% → 50%+ (Next priority) -4. **Web UI**: 0% → 50%+ (Future) - -## Test Best Practices - -### Writing Tests - -1. **Follow AAA Pattern** - - - Arrange: Set up test data - - Act: Execute the code - - Assert: Verify results - -2. **Test Edge Cases** - - - Invalid input - - Empty data - - Missing files - - Network failures - -3. **Mock External Dependencies** - - - Docker commands - - File system operations - - Network requests - -4. **Keep Tests Independent** - - Each test should be standalone - - Clean up after tests - - Don't rely on test execution order - -### Test Organization - -``` -tests/ -├── api/ # API endpoint tests -├── unit/ # Script unit tests -├── integration/ # Integration tests -├── e2e/ # End-to-end tests -├── performance/ # Performance tests (future) -├── security/ # Security tests (future) -└── helpers/ # Test utilities -``` - -## Continuous Improvement - -### Regular Tasks - -1. **Weekly**: Review test coverage reports -2. **Monthly**: Add tests for new features -3. **Quarterly**: Audit and improve test quality -4. **Before Release**: Ensure all critical paths are tested - -### Metrics to Track - -- Test coverage percentage -- Number of tests -- Test execution time -- Flaky test rate -- Test failure rate - -## See Also - -- [Testing Guide](TESTING.md) -- [Analytics Documentation](ANALYTICS.md) -- [API Documentation](API.md) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 9e721c7..cb07dc5 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -35,7 +35,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on 3. **Run script with more verbose output**: ```bash - bash -x ./setup-rpi.sh + bash -x ./scripts/setup-rpi.sh ``` 4. **Check disk space**: @@ -70,7 +70,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on ```bash docker --version - docker-compose --version + docker compose --version ``` ### Permission Denied Errors @@ -103,7 +103,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on ### Server Won't Start -**Symptoms**: `./manage.sh start` fails or server exits immediately +**Symptoms**: `./scripts/manage.sh start` fails or server exits immediately **Diagnostic Steps**: @@ -118,7 +118,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on 2. **View detailed logs**: ```bash - docker-compose logs + docker compose logs ``` 3. **Check for port conflicts**: @@ -143,7 +143,7 @@ This guide helps you diagnose and fix common issues with the Minecraft Server on ```bash echo "eula=true" > ~/minecraft-server/eula.txt -./manage.sh restart +./scripts/manage.sh restart ``` #### Out of Memory @@ -202,11 +202,60 @@ ports: 4. **Delete corrupted world**: ```bash - ./manage.sh stop + ./scripts/manage.sh stop rm -rf data/world* - ./manage.sh start + ./scripts/manage.sh start ``` +### Server Restart Loop + +**Symptoms**: The container starts, stops, and starts again in a cycle. + +**Diagnosis**: + +```bash +docker ps -a | grep minecraft-server # Container status +docker logs --tail 100 minecraft-server # Recent logs +docker inspect minecraft-server | grep -A 5 RestartCount +``` + +**Common causes and fixes**: + +1. **Out of memory** — logs show `OutOfMemoryError`, or Docker kills the container. + Lower `MEMORY_MIN`/`MEMORY_MAX` in `docker-compose.yml` and check `free -h`. + +2. **Server JAR missing or corrupted** — "Could not find or load main class" or + "Unable to access jarfile". Stop the server, check `ls -lh data/server.jar`; + the start script re-downloads it on the next start if it is absent. + +3. **Port already in use** — "Address already in use". Find the holder with + `sudo lsof -i :25565` and stop it, or change the port in `docker-compose.yml`. + +4. **Corrupted world data** — crashes during world loading. Stop the server and + move the world aside: `mv data/world data/world.backup.$(date +%Y%m%d)`. + +5. **Healthcheck failing** — the container restarts even though Java is running. + Raise `healthcheck.start_period` (e.g. `180s`) and `retries` in `docker-compose.yml`. + +6. **Disk full** — "No space left on device". Check `df -h` and run + `./scripts/log-manager.sh clean`. + +7. **Insufficient permissions** — permission denied in the logs. Run + `./scripts/fix-permissions.sh`, or + `sudo chown -R $USER:$USER data/ backups/ plugins/`. + +**Breaking the loop to investigate**: set `restart: "no"` in `docker-compose.yml`, +run `docker compose up -d`, and watch `docker logs -f minecraft-server`. Restore +`restart: on-failure` once the cause is fixed. + +**Deeper debugging**: + +```bash +docker stats minecraft-server # CPU and memory +vcgencmd measure_temp && vcgencmd get_throttled # Pi thermal state +docker exec minecraft-server java -version # Java inside the container +``` + ### Server Download Fails **Symptoms**: "Failed to download Minecraft server jar" @@ -241,14 +290,14 @@ ports: 1. **Verify server is running**: ```bash - ./manage.sh status + ./scripts/manage.sh status # Should show "Up" ``` 2. **Check server logs**: ```bash - ./manage.sh logs + ./scripts/manage.sh logs # Look for "Done!" message ``` @@ -438,7 +487,7 @@ ports: ```bash # Add to crontab for daily restart - 0 4 * * * cd ~/minecraft-server && ./manage.sh restart + 0 4 * * * cd ~/minecraft-server && ./scripts/manage.sh restart ``` ### High CPU Usage @@ -480,17 +529,17 @@ ports: 1. **Remove old containers**: ```bash - docker-compose down + docker compose down docker rm minecraft-server - docker-compose up -d + docker compose up -d ``` 2. **Rebuild image**: ```bash - docker-compose down - docker-compose build --no-cache - docker-compose up -d + docker compose down + docker compose build --no-cache + docker compose up -d ``` 3. **Check Docker logs**: @@ -499,6 +548,36 @@ ports: docker logs minecraft-server ``` +### Docker Compose Plugin Conflict + +**Symptoms**: `apt` fails while installing `docker-compose`: + +```text +dpkg: error processing archive ... trying to overwrite +'/usr/libexec/docker/cli-plugins/docker-compose', +which is also in package docker-compose-plugin +``` + +**Cause**: Docker Engine 20.10+ ships Compose as a plugin (`docker compose`, +with a space). The standalone `docker-compose` package conflicts with it and is +not needed. + +**Fix**: + +```bash +sudo apt-get remove --purge docker-compose +sudo apt-get autoremove && sudo apt-get autoclean +docker compose version # should print v2.x +``` + +If `docker compose version` still fails, install the plugin: +`sudo apt-get install -y docker-compose-plugin`. + +Use `docker compose ` everywhere — including in any systemd unit files +you wrote by hand (`ExecStart=/usr/bin/docker compose up -d`), followed by +`sudo systemctl daemon-reload`. The `Makefile` detects which form is available +and uses the plugin when present. + ### Docker Disk Space Full **Symptoms**: "No space left on device" @@ -568,9 +647,9 @@ ports: 2. **Restore from backup**: ```bash - ./manage.sh stop + ./scripts/manage.sh stop tar -xzf backups/minecraft_backup_*.tar.gz -C data/ - ./manage.sh start + ./scripts/manage.sh start ``` 3. **Consider using SSD**: @@ -626,42 +705,42 @@ ports: **Basic log viewing**: ```bash -./manage.sh logs +./scripts/manage.sh logs # Shows last 100 lines of server logs ``` **Search logs**: ```bash -./manage.sh logs-search "error" +./scripts/manage.sh logs-search "error" # Search for "error" in logs -./manage.sh logs-search -l ERROR +./scripts/manage.sh logs-search -l ERROR # Show all ERROR level messages -./manage.sh logs-search -d 2025-01-15 "crash" +./scripts/manage.sh logs-search -d 2025-01-15 "crash" # Search for "crash" on specific date -./manage.sh logs-search -r 2025-01-01 2025-01-31 "player joined" +./scripts/manage.sh logs-search -r 2025-01-01 2025-01-31 "player joined" # Search date range ``` **Log management**: ```bash -./manage.sh logs-manage all +./scripts/manage.sh logs-manage all # Run all log operations (rotate, index, errors, stats) -./manage.sh logs-manage index +./scripts/manage.sh logs-manage index # Parse and index logs for faster searching -./manage.sh logs-manage errors +./scripts/manage.sh logs-manage errors # Detect and report error patterns -./manage.sh logs-manage rotate +./scripts/manage.sh logs-manage rotate # Rotate and archive old logs -./manage.sh logs-manage stats +./scripts/manage.sh logs-manage stats # Show log statistics ``` @@ -679,7 +758,7 @@ Edit `config/log-management.conf` to configure: ```bash # Manually rotate logs -./manage.sh logs-manage rotate +./scripts/manage.sh logs-manage rotate # Or reduce retention period in config/log-management.conf LOG_RETENTION_DAYS=7 @@ -689,20 +768,20 @@ LOG_RETENTION_DAYS=7 ```bash # Re-index logs -./manage.sh logs-manage index +./scripts/manage.sh logs-manage index # Then search -./manage.sh logs-search "your search term" +./scripts/manage.sh logs-search "your search term" ``` **Too many errors detected**: ```bash # View error summary -./manage.sh logs-manage errors +./scripts/manage.sh logs-manage errors # Check specific error patterns -./manage.sh logs-search -l ERROR +./scripts/manage.sh logs-search -l ERROR ``` ## Getting Additional Help @@ -723,10 +802,10 @@ When asking for help, include: 2. **Server logs**: ```bash - docker-compose logs > logs.txt + docker compose logs > logs.txt # Or use log management - ./manage.sh logs-manage errors > errors.txt - ./manage.sh logs-search "error" > search_results.txt + ./scripts/manage.sh logs-manage errors > errors.txt + ./scripts/manage.sh logs-search "error" > search_results.txt ``` 3. **Configuration**: @@ -754,7 +833,7 @@ When asking for help, include: ### Best Practices -1. **Regular backups**: `./manage.sh backup` +1. **Regular backups**: `./scripts/manage.sh backup` 2. **Monitor resources**: `htop` and `docker stats` 3. **Keep system updated**: `sudo apt update && sudo apt upgrade` 4. **Use quality hardware**: Good SD card, proper cooling diff --git a/docs/WORKSPACE_ENHANCEMENTS.md b/docs/WORKSPACE_ENHANCEMENTS.md deleted file mode 100644 index 2a06963..0000000 --- a/docs/WORKSPACE_ENHANCEMENTS.md +++ /dev/null @@ -1,219 +0,0 @@ -# Workspace Enhancements Summary - -This document summarizes all the enhancements made to optimize the development workspace. - -## New Files Created - -### Documentation -- **ROADMAP.md** - Comprehensive development roadmap with phases and timelines -- **TASKS.md** - Detailed task breakdown with priorities and assignments -- **DEVELOPMENT.md** - Developer guide for contributing to the project -- **WORKSPACE_ENHANCEMENTS.md** - This file - -### Configuration Files -- **Makefile** - Convenient commands for server management -- **.editorconfig** - Consistent code formatting across editors -- **.pre-commit-config.yaml** - Pre-commit hooks for code quality -- **.env.example** - Environment variable template (create manually if needed) - -### VS Code Configuration -- **.vscode/settings.json** - Editor settings and file associations -- **.vscode/extensions.json** - Recommended extensions -- **.vscode/launch.json** - Debug configurations - -### CI/CD -- **.github/workflows/ci.yml** - GitHub Actions CI pipeline - -### Directory Structure -- **config/README.md** - Configuration directory documentation -- **scripts/README.md** - Scripts directory documentation - -## Optimizations Made - -### docker-compose.yml Enhancements -- ✅ Added environment variable support (from .env file) -- ✅ Added healthcheck configuration -- ✅ Added logging configuration with rotation -- ✅ Added resource limits and reservations -- ✅ Added custom network subnet configuration -- ✅ Added hostname configuration -- ✅ Made all settings configurable via environment variables - -### .gitignore Updates -- ✅ Added .env file exclusion -- ✅ Added config files exclusion (with exceptions) -- ✅ Added Python/Node.js exclusions for future features -- ✅ Added test coverage exclusions -- ✅ Better organization and comments - -## New Features Available - -### Makefile Commands -```bash -make help # Show all available commands -make install # Install dependencies -make start # Start server -make stop # Stop server -make restart # Restart server -make status # Check status -make logs # View logs -make backup # Create backup -make console # Attach to console -make build # Build Docker image -make clean # Clean Docker resources -make test # Run tests -make shell # Open container shell -make info # Show system information -``` - -### VS Code Integration -- Automatic formatting on save -- Shell script syntax checking -- YAML validation -- Docker integration -- Markdown linting -- Recommended extensions auto-install - -### Pre-commit Hooks -- Trailing whitespace removal -- End of file fixes -- YAML/JSON validation -- Large file checking -- Merge conflict detection -- Shell script linting (shellcheck) -- Markdown linting - -### CI/CD Pipeline -- Automated syntax checking -- Docker Compose validation -- Shell script validation -- Runs on every push and PR - -## Environment Variables - -Create a `.env` file in the root directory with these variables: - -```bash -# Minecraft Version -MINECRAFT_VERSION=1.20.4 - -# Memory Settings -MEMORY_MIN=1G -MEMORY_MAX=2G - -# Server Port -SERVER_PORT=25565 - -# EULA Acceptance -EULA=TRUE - -# Server Type -SERVER_TYPE=vanilla - -# Timezone -TZ=UTC - -# Backup Settings -BACKUP_RETENTION_DAYS=7 -BACKUP_SCHEDULE=daily -BACKUP_TIME=03:00 - -# Monitoring -ENABLE_MONITORING=true -MONITORING_PORT=9090 - -# RCON Settings -ENABLE_RCON=false -RCON_PORT=25575 -RCON_PASSWORD= - -# Dynamic DNS -DDNS_ENABLED=false -DDNS_PROVIDER=duckdns -DDNS_DOMAIN= -DDNS_TOKEN= - -# Cloud Backup -CLOUD_BACKUP_ENABLED=false -CLOUD_BACKUP_PROVIDER=s3 -AWS_ACCESS_KEY_ID= -AWS_SECRET_ACCESS_KEY= -AWS_BUCKET_NAME= -AWS_REGION=us-east-1 -``` - -## Next Steps - -1. **Create .env file** - ```bash - cp .env.example .env - # Edit .env with your settings - ``` - -2. **Install pre-commit hooks** (optional) - ```bash - pip install pre-commit - pre-commit install - ``` - -3. **Install VS Code extensions** (if using VS Code) - - Open VS Code in the project - - Install recommended extensions when prompted - -4. **Test the setup** - ```bash - make test - make build - ``` - -5. **Start developing** - - Review ROADMAP.md for planned features - - Check TASKS.md for specific tasks - - Read DEVELOPMENT.md for guidelines - -## Benefits - -### For Developers -- Consistent code formatting -- Automated quality checks -- Better IDE integration -- Clear development guidelines -- Comprehensive roadmap - -### For Users -- Easier configuration management -- Better documentation -- More reliable updates -- Clearer project direction - -### For Maintainers -- Automated testing -- Code quality enforcement -- Better organization -- Easier contribution process - -## Migration Notes - -### Existing Installations -No breaking changes! All enhancements are backward compatible: -- Existing `docker-compose.yml` still works -- Old `manage.sh` commands still work -- New features are optional - -### Upgrading -1. Pull latest changes -2. Copy `.env.example` to `.env` (optional) -3. Review new documentation -4. Test with `make test` - -## Support - -For questions about workspace enhancements: -- Check DEVELOPMENT.md -- Review ROADMAP.md for context -- Open a GitHub issue - ---- - -**Last Updated**: 2025-01-XX - diff --git a/docs/archive/API_DOCUMENTATION.md b/docs/archive/API_DOCUMENTATION.md deleted file mode 100644 index 0573291..0000000 --- a/docs/archive/API_DOCUMENTATION.md +++ /dev/null @@ -1,327 +0,0 @@ -# API Documentation Guide - -This guide covers the REST API documentation for the Minecraft Server Management system. - -## Overview - -The API provides comprehensive endpoints for: - -- Server control (start, stop, restart, commands) -- Backup management (create, list, restore, delete) -- Player management -- World and plugin management -- Configuration file management -- Monitoring and metrics -- User authentication and authorization -- API key management -- Dynamic DNS management - -## OpenAPI Specification - -The API is documented using OpenAPI 3.0 specification: - -- **File**: `api/openapi.yaml` -- **Format**: YAML -- **Version**: 3.0.3 - -## Viewing Documentation - -### Method 1: Swagger Editor (Online) - -1. Go to [Swagger Editor](https://editor.swagger.io/) -2. Copy contents of `api/openapi.yaml` -3. Paste into editor -4. View interactive documentation - -### Method 2: Swagger UI (Docker) - -```bash -# Serve with Docker -docker run -d \ - --name swagger-ui \ - -p 8081:8080 \ - -e SWAGGER_JSON=/openapi.yaml \ - -v $(pwd)/api/openapi.yaml:/openapi.yaml:ro \ - swaggerapi/swagger-ui - -# Open in browser -open http://localhost:8081 -``` - -### Method 3: Using Script - -```bash -# Serve API docs -./scripts/serve-api-docs.sh - -# Or with custom port -PORT=9000 ./scripts/serve-api-docs.sh -``` - -### Method 4: Redoc - -```bash -# Serve with Redoc -docker run -d \ - --name redoc \ - -p 8081:80 \ - -v $(pwd)/api/openapi.yaml:/usr/share/nginx/html/openapi.yaml:ro \ - redocly/redoc - -# Open in browser -open http://localhost:8081 -``` - -## API Base URL - -- **Local**: `http://localhost:8080` -- **Raspberry Pi**: `http://minecraft-server.local:8080` -- **Production**: `https://your-domain.com:8080` - -## Authentication - -The API supports three authentication methods: - -### 1. API Key (Recommended for Automation) - -```bash -curl -H "X-API-Key: your-api-key" \ - http://localhost:8080/api/status -``` - -### 2. Bearer Token (JWT) - -```bash -# Login to get token -TOKEN=$(curl -X POST http://localhost:8080/api/auth/login \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"password"}' \ - | jq -r '.token') - -# Use token -curl -H "Authorization: Bearer $TOKEN" \ - http://localhost:8080/api/status -``` - -### 3. Session Cookie - -```bash -# Login (creates session) -curl -X POST http://localhost:8080/api/auth/login \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"password"}' \ - -c cookies.txt - -# Use session -curl -b cookies.txt http://localhost:8080/api/status -``` - -## Endpoint Categories - -### Health Check - -- `GET /api/health` - Check API health (no auth required) - -### Authentication - -- `POST /api/auth/register` - Register new user -- `POST /api/auth/login` - Login user -- `POST /api/auth/logout` - Logout user -- `GET /api/auth/me` - Get current user - -### Server Control - -- `GET /api/status` - Get server status -- `POST /api/server/start` - Start server -- `POST /api/server/stop` - Stop server -- `POST /api/server/restart` - Restart server -- `POST /api/server/command` - Send server command - -### Backups - -- `POST /api/backup` - Create backup -- `GET /api/backups` - List backups -- `POST /api/backups/{filename}/restore` - Restore backup -- `DELETE /api/backups/{filename}` - Delete backup - -### Players - -- `GET /api/players` - List players - -### Worlds - -- `GET /api/worlds` - List worlds - -### Plugins - -- `GET /api/plugins` - List plugins - -### Configuration - -- `GET /api/config/files` - List configuration files -- `GET /api/config/files/{filename}` - Get configuration file -- `POST /api/config/files/{filename}` - Update configuration file -- `POST /api/config/files/{filename}/validate` - Validate configuration file - -### Logs - -- `GET /api/logs` - Get server logs - -### Metrics - -- `GET /api/metrics` - Get server metrics - -### API Keys - -- `GET /api/keys` - List API keys -- `POST /api/keys` - Create API key -- `DELETE /api/keys/{key_id}` - Delete API key -- `PUT /api/keys/{key_id}/enable` - Enable API key -- `PUT /api/keys/{key_id}/disable` - Disable API key - -### Users - -- `GET /api/users` - List users -- `PUT /api/users/{username}/role` - Update user role -- `DELETE /api/users/{username}` - Delete user -- `PUT /api/users/{username}/enable` - Enable user -- `PUT /api/users/{username}/disable` - Disable user - -### Dynamic DNS - -- `GET /api/ddns/status` - Get DDNS status -- `POST /api/ddns/update` - Update DDNS -- `GET /api/ddns/config` - Get DDNS configuration -- `POST /api/ddns/config` - Update DDNS configuration - -## Example Requests - -### Start Server - -```bash -curl -X POST http://localhost:8080/api/server/start \ - -H "X-API-Key: your-api-key" \ - -H "Content-Type: application/json" -``` - -### Create Backup - -```bash -curl -X POST http://localhost:8080/api/backup \ - -H "X-API-Key: your-api-key" \ - -H "Content-Type: application/json" -``` - -### Get Server Status - -```bash -curl http://localhost:8080/api/status \ - -H "X-API-Key: your-api-key" -``` - -### Send Server Command - -```bash -curl -X POST http://localhost:8080/api/server/command \ - -H "X-API-Key: your-api-key" \ - -H "Content-Type: application/json" \ - -d '{"command": "say Hello from API"}' -``` - -### List Backups - -```bash -curl http://localhost:8080/api/backups \ - -H "X-API-Key: your-api-key" -``` - -## Response Format - -### Success Response - -```json -{ - "success": true, - "message": "Operation completed", - "data": { ... } -} -``` - -### Error Response - -```json -{ - "error": "Error message", - "code": "ERROR_CODE" -} -``` - -## Status Codes - -- `200` - Success -- `201` - Created -- `400` - Bad Request -- `401` - Unauthorized -- `403` - Forbidden -- `404` - Not Found -- `500` - Internal Server Error - -## Rate Limiting - -Currently no rate limiting is implemented. Consider implementing for production use. - -## CORS - -CORS is enabled for all origins. Configure in `config/api.conf` for production. - -## Updating Documentation - -When adding new endpoints: - -1. Update `api/openapi.yaml` with new endpoint -2. Add request/response schemas -3. Update this documentation -4. Test with Swagger UI - -## Tools - -### Generate Client Libraries - -Use [OpenAPI Generator](https://openapi-generator.tech/): - -```bash -# Generate Python client -openapi-generator generate \ - -i api/openapi.yaml \ - -g python \ - -o clients/python - -# Generate JavaScript client -openapi-generator generate \ - -i api/openapi.yaml \ - -g javascript \ - -o clients/javascript -``` - -### Validate Specification - -```bash -# Install swagger-cli -npm install -g @apidevtools/swagger-cli - -# Validate -swagger-cli validate api/openapi.yaml -``` - -## Resources - -- [OpenAPI Specification](https://swagger.io/specification/) -- [Swagger Editor](https://editor.swagger.io/) -- [Swagger UI](https://swagger.io/tools/swagger-ui/) -- [Redoc](https://redocly.com/docs/redoc/) - -## See Also - -- [API Guide](API.md) - Detailed API usage guide -- [API Keys Guide](API_KEYS.md) - API key management -- [RBAC Guide](RBAC.md) - Role-based access control diff --git a/docs/archive/CI_CD_ENHANCEMENTS.md b/docs/archive/CI_CD_ENHANCEMENTS.md deleted file mode 100644 index 2ce627e..0000000 --- a/docs/archive/CI_CD_ENHANCEMENTS.md +++ /dev/null @@ -1,288 +0,0 @@ -# CI/CD Testing Enhancements - -This document describes the testing framework enhancements integrated into the CI/CD pipeline. - -## Overview - -The CI/CD pipeline has been enhanced to leverage all the new testing framework capabilities, providing better test coverage, faster execution, and more comprehensive reporting. - -## Enhanced Python Tests Job - -The `python-tests` job in `.github/workflows/main.yml` now includes: - -### 1. Test Requirements Installation - -```yaml -- name: Install dependencies - run: | - pip install --upgrade pip - pip install -r api/requirements.txt - pip install -r api/requirements-test.txt -``` - -Installs all testing dependencies including: - -- `pytest-xdist` for parallel execution -- `pytest-mock` for enhanced mocking -- `jsonschema` for contract testing -- `pyyaml` for OpenAPI schema parsing - -### 2. Parallel Test Execution - -```yaml -- name: Run API tests (parallel) - run: | - cd tests/api - pytest -v -n auto \ - --cov=../../api \ - --cov-config=../../.coverage-config.ini \ - --cov-report=term-missing \ - --cov-report=html:htmlcov \ - --cov-report=json:coverage.json \ - --cov-report=xml:coverage.xml \ - -ra -``` - -**Features**: - -- `-n auto` - Automatically detects CPU count and runs tests in parallel -- Multiple coverage report formats (HTML, JSON, XML) -- Detailed test output with `-ra` (show all test info) - -**Benefits**: - -- Faster test execution (typically 2-4x faster) -- Better resource utilization -- Multiple report formats for different tools - -### 3. Performance Tests - -```yaml -- name: Run performance tests - run: | - cd tests/api - pytest -v -m performance || echo "Performance tests completed" -``` - -Runs all tests marked with `@pytest.mark.performance`: - -- Endpoint response time tests -- Load testing -- Throughput measurement - -**Note**: Uses `|| echo` to prevent job failure if performance tests have issues (non-blocking) - -### 4. Contract Tests - -```yaml -- name: Run contract tests - run: | - cd tests/api - pytest -v -m contract || echo "Contract tests completed" -``` - -Runs all tests marked with `@pytest.mark.contract`: - -- API response schema validation -- Request schema validation -- OpenAPI compliance checks - -**Note**: Non-blocking to allow CI to continue even if schema validation has issues - -### 5. Coverage Gap Analysis - -```yaml -- name: Analyze coverage gaps - run: | - chmod +x scripts/analyze-coverage-gaps.sh - ./scripts/analyze-coverage-gaps.sh analyze || echo "Coverage gap analysis completed" -``` - -Analyzes test coverage and identifies: - -- Files with coverage < 80% -- Missing line numbers -- Test improvement suggestions - -Generates `coverage-gaps.txt` report. - -### 6. Coverage Report Artifacts - -```yaml -- name: Upload coverage reports - uses: actions/upload-artifact@v4 - if: always() - with: - name: coverage-reports - path: | - coverage.json - coverage.xml - htmlcov/ - coverage-gaps.txt - retention-days: 30 -``` - -Uploads all coverage reports as GitHub Actions artifacts: - -- **coverage.json** - JSON format for programmatic access -- **coverage.xml** - XML format for Codecov and other tools -- **htmlcov/** - HTML report for visual inspection -- **coverage-gaps.txt** - Gap analysis report - -**Access**: Download from GitHub Actions run page under "Artifacts" - -### 7. Codecov Integration - -```yaml -- name: Upload coverage to Codecov - uses: codecov/codecov-action@v4 - with: - files: ./coverage.xml - flags: unittests - name: codecov-umbrella - fail_ci_if_error: false -``` - -Uploads coverage to Codecov for: - -- Coverage tracking over time -- PR coverage comments -- Coverage badges -- Coverage trends - -## Test Execution Flow - -``` -1. Install Dependencies - ├── Production dependencies (api/requirements.txt) - └── Test dependencies (api/requirements-test.txt) - -2. Run Main Test Suite (Parallel) - ├── All unit tests - ├── Integration tests - └── Generate coverage reports - -3. Run Performance Tests - └── Endpoint performance validation - -4. Run Contract Tests - └── API schema validation - -5. Analyze Coverage Gaps - └── Identify untested code - -6. Upload Artifacts - ├── Coverage reports - └── Gap analysis - -7. Upload to Codecov - └── Coverage tracking -``` - -## Benefits - -### Speed Improvements - -- **Parallel Execution**: 2-4x faster test runs -- **Efficient Resource Use**: Better CPU utilization -- **Faster Feedback**: Quicker CI results - -### Better Coverage - -- **Multiple Report Formats**: HTML for humans, JSON/XML for tools -- **Gap Analysis**: Identifies areas needing tests -- **Codecov Integration**: Track coverage trends - -### Quality Assurance - -- **Performance Tests**: Catch performance regressions -- **Contract Tests**: Ensure API compliance -- **Comprehensive Reporting**: Multiple views of test results - -## Accessing Results - -### Coverage Reports - -1. Go to GitHub Actions run page -2. Click on "python-tests" job -3. Download "coverage-reports" artifact -4. Extract and open `htmlcov/index.html` in browser - -### Coverage Gaps - -1. Download "coverage-reports" artifact -2. Open `coverage-gaps.txt` to see: - - Files with low coverage - - Missing line numbers - - Improvement suggestions - -### Codecov Dashboard - -1. Visit Codecov dashboard (if configured) -2. View coverage trends -3. See PR coverage comments -4. Track coverage over time - -## Configuration - -### Test Markers - -Tests are organized using pytest markers: - -- `@pytest.mark.unit` - Unit tests -- `@pytest.mark.integration` - Integration tests -- `@pytest.mark.api` - API endpoint tests -- `@pytest.mark.performance` - Performance tests -- `@pytest.mark.contract` - Contract tests -- `@pytest.mark.slow` - Slow running tests - -### Coverage Threshold - -Configured in `.coverage-config.ini`: - -- Minimum coverage: 60% -- Target coverage: 80% - -### Parallel Execution - -- **Auto-detection**: `-n auto` uses all available CPUs -- **Manual**: Can specify `-n 4` for 4 workers -- **Optimal**: Usually 2-4x CPU count works best - -## Troubleshooting - -### Tests Failing in CI - -1. Check test output in GitHub Actions -2. Download coverage reports artifact -3. Review coverage-gaps.txt for missing tests -4. Check performance test thresholds - -### Coverage Not Uploading - -1. Verify `coverage.xml` is generated -2. Check Codecov token is configured -3. Review Codecov action logs - -### Performance Tests Failing - -1. Check if thresholds are too strict -2. Review performance test output -3. Consider adjusting timeout values - -## Future Enhancements - -Potential future improvements: - -1. **Test Result Caching**: Cache test results for faster runs -2. **Matrix Testing**: Test on multiple Python versions -3. **Coverage Badges**: Auto-update coverage badges -4. **PR Comments**: Auto-comment coverage on PRs -5. **Performance Baselines**: Track performance over time - -## Resources - -- [GitHub Actions Documentation](https://docs.github.com/en/actions) -- [pytest-xdist Documentation](https://pytest-xdist.readthedocs.io/) -- [Codecov Documentation](https://docs.codecov.com/) -- [Testing Enhancements Guide](../docs/TESTING_ENHANCEMENTS.md) diff --git a/docs/archive/CI_CD_OPTIMIZATIONS.md b/docs/archive/CI_CD_OPTIMIZATIONS.md deleted file mode 100644 index e85ac07..0000000 --- a/docs/archive/CI_CD_OPTIMIZATIONS.md +++ /dev/null @@ -1,261 +0,0 @@ -# CI/CD Pipeline Optimizations - -This document describes the optimizations implemented in the CI/CD pipeline to ensure clean and quick operations. - -## Overview - -The pipeline has been optimized for: -- **Speed**: Reduced build times through caching and parallelization -- **Reliability**: Better error handling and resource management -- **Efficiency**: Reduced resource usage and costs -- **Maintainability**: Cleaner, more organized workflow - -## Implemented Optimizations - -### 1. Dependency Caching - -#### Python Dependencies -- **Implementation**: Uses GitHub Actions built-in pip caching -- **Benefit**: Avoids re-downloading Python packages on every run -- **Location**: `python-tests` job -- **Cache Key**: Based on `api/requirements.txt` hash - -```yaml -- name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.9' - cache: 'pip' - cache-dependency-path: api/requirements.txt -``` - -#### Node.js Dependencies -- **Implementation**: Uses GitHub Actions built-in npm caching -- **Benefit**: Faster frontend test execution -- **Location**: `frontend-tests` and `playwright-tests` jobs -- **Cache Key**: Based on `web/package-lock.json` hash - -#### BATS Installation -- **Implementation**: Custom cache for BATS binary -- **Benefit**: Skips BATS installation when cached -- **Location**: `bash-tests` job -- **Cache Key**: `bats-${{ runner.os }}-v1` - -#### APT Packages -- **Implementation**: Caches `/var/cache/apt` directory -- **Benefit**: Faster package installation in image builds -- **Location**: `build-rpi-image` job -- **Cache Key**: `apt-${{ runner.os }}-rpi-build-tools` - -#### Raspberry Pi OS Base Image -- **Implementation**: Caches downloaded and extracted base image -- **Benefit**: Skips 5-15 minute download on cache hits -- **Location**: `build-rpi-image` job -- **Cache Key**: `rpi-os-lite-2024-01-11-arm64` -- **Note**: Cache key should be updated when base image version changes - -### 2. Docker Build Optimizations - -#### Build Cache -- **Implementation**: GitHub Actions cache for Docker layers -- **Benefit**: Reuses layers from previous builds -- **Cache Scope**: `build-docker` to isolate cache per job -- **Mode**: `max` for maximum cache utilization - -```yaml -cache-from: type=gha,scope=build-docker -cache-to: type=gha,mode=max,scope=build-docker -``` - -#### Build Context -- **Implementation**: `.dockerignore` file excludes unnecessary files -- **Benefit**: Smaller build context = faster uploads -- **Excluded**: Documentation, tests, web frontend, CI/CD files - -### 3. Image Build Optimizations - -#### Reduced Wait Times -- **Before**: 3 seconds wait after partition operations -- **After**: 1 second wait with timeout-based verification -- **Benefit**: Faster image customization step - -```bash -# Optimized partition waiting -sleep 1 -sudo partprobe $LOOP_DEVICE -sleep 1 - -# Timeout-based verification -timeout=10 -while [ $timeout -gt 0 ] && [ ! -e "${LOOP_DEVICE}p1" ]; do - sleep 0.5 - timeout=$((timeout - 1)) -done -``` - -#### Compression Optimization -- **Before**: `xz -9` (maximum compression, slow) -- **After**: `xz -6` (good compression, faster) -- **Benefit**: 2-3x faster compression with minimal size increase -- **Trade-off**: ~5-10% larger compressed file, but much faster - -#### Artifact Optimization -- **Implementation**: Only upload compressed `.img.xz` files -- **Benefit**: Smaller artifacts, faster uploads -- **Compression Level**: 6 (balanced) - -### 4. Job Parallelization - -#### Current Structure -- Lint, Python tests, and Bash tests run in parallel -- Frontend and Playwright tests run in parallel (non-blocking) -- Docker build waits for critical tests -- Image build waits for Docker build - -#### Optimization Opportunities -- All test jobs can run in parallel (already implemented) -- Non-blocking tests don't block critical path -- Summary job aggregates all results - -### 5. Resource Management - -#### Timeouts -- **Image Build**: 120 minutes timeout -- **Playwright Tests**: 60 minutes timeout -- **Benefit**: Prevents hanging jobs from consuming resources - -#### APT Package Installation -- **Optimization**: `--no-install-recommends` flag -- **Benefit**: Installs only essential packages, faster installation - -### 6. Error Handling - -#### Image Verification -- **Implementation**: Verify base image exists after extraction -- **Benefit**: Fails fast if extraction fails - -#### Artifact Upload -- **Implementation**: `if-no-files-found: error` -- **Benefit**: Fails if expected artifacts are missing - -## Performance Improvements - -### Estimated Time Savings - -| Optimization | Time Saved | Frequency | -|-------------|------------|-----------| -| Python pip cache | 30-60s | Every run | -| Node.js cache | 20-40s | Every run | -| BATS cache | 10-20s | Every run | -| APT cache | 15-30s | Image builds | -| RPi OS image cache | 5-15 min | Image builds (cache hits) | -| Compression optimization | 2-5 min | Image builds | -| Reduced wait times | 4-6s | Image builds | -| **Total (typical run)** | **1-2 min** | Every run | -| **Total (image build)** | **7-20 min** | Image builds | - -### Cache Hit Rates - -- **Python/Node caches**: ~95% hit rate (changes only when dependencies update) -- **BATS cache**: ~100% hit rate (rarely changes) -- **APT cache**: ~80% hit rate (changes with workflow updates) -- **RPi OS image cache**: ~50% hit rate (changes with base image updates) - -## Best Practices - -### 1. Cache Key Management - -- Use stable cache keys for rarely-changing dependencies -- Include version numbers in cache keys for base images -- Use hash-based keys for frequently-changing dependencies - -### 2. Compression Trade-offs - -- Use `-6` for xz compression (good balance) -- Use `-9` only if file size is critical -- Consider gzip for faster compression if size isn't critical - -### 3. Timeout Settings - -- Set appropriate timeouts for long-running jobs -- Use shorter timeouts for quick operations -- Monitor job durations and adjust as needed - -### 4. Dependency Updates - -- Update cache keys when dependency versions change -- Clear caches if builds become inconsistent -- Monitor cache sizes and clean up old caches - -## Future Optimization Opportunities - -### 1. Matrix Builds -- Test on multiple Python versions (3.9, 3.10, 3.11) -- Test on multiple Node.js versions (18, 20, 22) -- **Benefit**: Better compatibility testing - -### 2. Larger Runners -- Use `ubuntu-latest-4-cores` for image builds -- **Benefit**: Faster compression and operations -- **Cost**: Higher runner costs - -### 3. Parallel Image Operations -- Mount and customize in parallel where possible -- **Benefit**: Faster image customization - -### 4. Incremental Builds -- Only rebuild changed components -- **Benefit**: Faster builds for small changes - -### 5. Docker Layer Optimization -- Further optimize Dockerfile layer ordering -- **Benefit**: Better cache utilization - -## Monitoring - -### Key Metrics to Track - -1. **Job Duration**: Monitor average job times -2. **Cache Hit Rates**: Track cache effectiveness -3. **Resource Usage**: Monitor runner resource consumption -4. **Failure Rates**: Track job failure frequency -5. **Cost**: Monitor GitHub Actions minutes used - -### Tools - -- GitHub Actions analytics dashboard -- Workflow run summaries -- Cache usage statistics - -## Troubleshooting - -### Cache Issues - -**Problem**: Cache not being used -- **Solution**: Check cache key matches -- **Solution**: Verify cache path is correct -- **Solution**: Check cache size limits - -**Problem**: Stale cache causing failures -- **Solution**: Update cache key -- **Solution**: Clear cache manually -- **Solution**: Add cache version to key - -### Performance Issues - -**Problem**: Slow builds -- **Solution**: Check cache hit rates -- **Solution**: Verify optimizations are applied -- **Solution**: Consider larger runners - -**Problem**: Timeouts -- **Solution**: Increase timeout values -- **Solution**: Optimize slow operations -- **Solution**: Split long-running jobs - -## References - -- [GitHub Actions Caching](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) -- [Docker Build Cache](https://docs.docker.com/build/cache/) -- [XZ Compression Options](https://tukaani.org/xz/manual/xz.html) - diff --git a/docs/archive/CI_CD_PIPELINE.md b/docs/archive/CI_CD_PIPELINE.md deleted file mode 100644 index 44efb3b..0000000 --- a/docs/archive/CI_CD_PIPELINE.md +++ /dev/null @@ -1,243 +0,0 @@ -# CI/CD Pipeline Documentation - -## Overview - -The unified CI/CD pipeline (`main.yml`) combines all testing, building, and deployment workflows into a single comprehensive pipeline. - -## Pipeline Structure - -### Jobs Overview - -1. **Lint** - Syntax and validation checks (blocking) -2. **Python Tests** - API tests (blocking) -3. **Bash Tests** - Shell script tests (blocking) -4. **Frontend Tests** - Vitest unit tests (non-blocking) -5. **Playwright Tests** - E2E browser tests (non-blocking) -6. **Build Docker** - Docker image build (blocking) -7. **Build RPi Image** - Raspberry Pi image creation (conditional) -8. **Summary** - Pipeline status summary - -### Job Dependencies - -``` -lint ──┐ - ├──> build-docker ──> build-rpi-image -python-tests ──┘ -bash-tests ───┘ - -frontend-tests (parallel, non-blocking) -playwright-tests (parallel, non-blocking) - -All jobs ──> summary -``` - -## Non-Blocking Tests - -### Frontend Tests - -- **Status**: Non-blocking (`continue-on-error: true`) -- **Purpose**: Unit tests for React components -- **Failure Impact**: Pipeline continues, failure is reported in summary - -### Playwright Tests - -- **Status**: Non-blocking (`continue-on-error: true`) -- **Purpose**: End-to-end browser automation tests -- **Timeout**: 60 minutes -- **Failure Impact**: Pipeline continues, test report uploaded as artifact -- **Artifacts**: Playwright HTML report (retained for 30 days) - -## Raspberry Pi Image Building - -### When Images Are Built - -Images are automatically built when: - -- Pushing to `main` branch -- Manual workflow dispatch with `build_image: true` -- Creating a release tag - -### Image Contents - -The generated `.img` file includes: - -1. **Base System**: Raspberry Pi OS Lite (64-bit) -2. **Pre-configured Services**: - - SSH enabled - - Hostname: `minecraft-server` - - WiFi configuration (optional) -3. **First-Boot Script**: - - Updates system packages - - Installs Docker and Docker Compose - - Installs Node.js for web interface - - Clones repository - - Runs setup script - - Configures Minecraft server - -### Image Specifications - -- **Format**: Compressed `.img.xz` file -- **Size**: ~4GB (expandable on first boot) -- **Architecture**: ARM64 (Raspberry Pi 5) -- **Base OS**: Raspberry Pi OS Lite (Bookworm) - -### Using the Image - -1. **Download** the `.img.xz` file from: - - - Workflow artifacts (for main branch builds) - - GitHub Releases (for tagged releases) - -2. **Extract** the image: - - ```bash - xz -d minecraft-server-rpi5-YYYYMMDD.img.xz - ``` - -3. **Flash** to microSD card: - - ```bash - # On Linux/macOS - sudo dd if=minecraft-server-rpi5-YYYYMMDD.img of=/dev/sdX bs=4M status=progress - - # Or use Raspberry Pi Imager - ``` - -4. **Boot** the Raspberry Pi: - - - Insert microSD card - - Connect power and network - - Wait 10-20 minutes for first-boot setup - - SSH into `minecraft-server.local` or check IP - -5. **Verify** setup: - ```bash - ssh pi@minecraft-server.local - cd ~/minecraft-server - ./manage.sh status - ``` - -## Pipeline Triggers - -### Automatic Triggers - -- **Push to main/develop**: Runs all tests and builds -- **Pull Request**: Runs all tests (no image build) -- **Push to main**: Builds Raspberry Pi image - -### Manual Triggers - -Use GitHub Actions UI to manually trigger: - -- Run all tests -- Build image (set `build_image: true`) - -## Critical vs Non-Critical Jobs - -### Critical (Must Pass) - -- ✅ Lint -- ✅ Python Tests -- ✅ Bash Tests -- ✅ Docker Build - -### Non-Critical (Can Fail) - -- ⚠️ Frontend Tests -- ⚠️ Playwright Tests - -## Artifacts - -### Playwright Report - -- **Location**: `web/playwright-report/` -- **Retention**: 30 days -- **Access**: Download from workflow run - -### Raspberry Pi Image - -- **Location**: Root directory -- **Format**: `.img.xz` (compressed) -- **Retention**: 90 days -- **Access**: - - Artifacts (main branch) - - GitHub Releases (tags) - -## Troubleshooting - -### Playwright Tests Failing - -Since Playwright tests are non-blocking, failures won't block the pipeline. To investigate: - -1. Download the Playwright report artifact -2. Open `index.html` in a browser -3. Review test failures and screenshots -4. Check test logs for errors - -### Image Build Failing - -Common issues: - -1. **Download timeout**: Raspberry Pi OS download may timeout - - - **Solution**: Workflow will retry, or manually trigger - -2. **Disk space**: Image building requires ~10GB free space - - - **Solution**: GitHub Actions runners have sufficient space - -3. **QEMU issues**: ARM emulation may fail - - **Solution**: Check QEMU setup step logs - -### Pipeline Summary - -The summary job provides an overview of all job results. Check the workflow run summary for: - -- Job status (✅ success, ❌ failure, ⚠️ skipped) -- Critical job failures -- Non-critical job warnings - -## Migration from Separate Workflows - -The old separate workflows are still present but can be disabled: - -- `ci.yml` → Merged into `main.yml` (lint job) -- `tests.yml` → Merged into `main.yml` (python-tests, bash-tests) -- `playwright.yml` → Merged into `main.yml` (playwright-tests, non-blocking) -- `coverage.yml` → Can be kept separate or merged -- `release.yml` → Image building replaces Docker image push - -To disable old workflows, add this to each: - -```yaml -on: - workflow_dispatch: # Only manual trigger -``` - -## Optimizations - -The pipeline has been optimized for speed and efficiency. See [CI/CD Optimizations](CI_CD_OPTIMIZATIONS.md) for detailed information about: - -- Dependency caching (Python, Node.js, BATS, APT, RPi OS image) -- Docker build optimizations -- Image build optimizations -- Job parallelization -- Resource management - -**Key Benefits:** -- 1-2 minutes saved on typical runs -- 7-20 minutes saved on image builds (with cache hits) -- Reduced resource usage -- Faster feedback cycles - -## Future Enhancements - -Potential improvements: - -1. **Matrix builds**: Test on multiple Python/Node versions -2. **Docker registry push**: Push images to GHCR -3. **Image signing**: Sign images for security -4. **Automated testing**: Test the built image in QEMU -5. **Multi-architecture**: Support Raspberry Pi 4 (ARM32) -6. **Larger runners**: Use 4-core runners for image builds -7. **Parallel operations**: Further parallelize image customization diff --git a/docs/archive/CONSOLIDATION_NOTES.md b/docs/archive/CONSOLIDATION_NOTES.md deleted file mode 100644 index af871b6..0000000 --- a/docs/archive/CONSOLIDATION_NOTES.md +++ /dev/null @@ -1,120 +0,0 @@ -# Documentation Consolidation Notes - -This document explains the documentation reorganization that took place to improve organization and reduce redundancy. - -## Changes Made - -### 1. Created Documentation Index - -- **New**: `docs/INDEX.md` - Central navigation hub for all documentation -- Provides organized access to all docs by category -- Includes quick navigation and topic-based organization - -### 2. Consolidated Implementation Summaries - -- **Archived**: Multiple implementation summary files moved to `docs/archive/` -- **Reason**: These were historical snapshots that duplicated information in CHANGELOG.md -- **Action**: Future implementation notes should go directly in CHANGELOG.md - -### 3. Reorganized README References - -- **Updated**: Main README.md documentation section -- **Improvement**: Clearer categorization (Getting Started, User Guides, Developer Guides) -- **Added**: Link to documentation index for easy navigation - -### 4. Created Documentation README - -- **New**: `docs/README.md` - Explains documentation structure -- **Purpose**: Helps contributors understand where to add new docs - -### 5. Archive Directory - -- **Created**: `docs/archive/` for superseded documentation -- **Purpose**: Preserve historical documents without cluttering main docs -- **Note**: Archived files are still accessible but marked as historical - -## Documentation Structure - -### Before - -- Multiple implementation summary files in root -- Duplicate files in root and docs/ -- No clear navigation structure -- Hard to find specific documentation - -### After - -- Single documentation index (`docs/INDEX.md`) -- Clear categorization (User/Developer/Reference) -- Archived historical documents -- Easy navigation from README - -## File Locations - -### Current Documentation - -- **Main Index**: `docs/INDEX.md` -- **Installation**: `docs/INSTALL.md` -- **Quick Reference**: `docs/QUICK_REFERENCE.md` -- **User Guides**: `docs/*.md` (feature-specific) -- **Developer Guides**: `docs/DEVELOPMENT.md`, `docs/TESTING.md`, etc. - -### Archived Files - -- `docs/archive/IMPLEMENTATION_SUMMARY.md` -- `docs/archive/IMPLEMENTATION_SUMMARY_P1.md` -- `docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md` -- `docs/archive/IMPLEMENTATION_SUMMARY_docs.md` - -## Best Practices Going Forward - -### Adding New Documentation - -1. **Choose the right location**: - - - User guides → `docs/` (feature name) - - Developer guides → `docs/DEVELOPMENT.md` or new file - - Reference → `docs/QUICK_REFERENCE.md` or `docs/CONFIGURATION_EXAMPLES.md` - -2. **Update the index**: - - - Add entry to `docs/INDEX.md` - - Update appropriate category section - - Add cross-references if needed - -3. **Update README**: - - Add link in main README.md if user-facing - - Keep documentation section organized - -### Version History - -- **Use CHANGELOG.md** for implementation summaries -- **Avoid** creating separate implementation summary files -- **Document** features as they're implemented in CHANGELOG - -### Consolidation - -- **Review periodically** for duplicate content -- **Archive** superseded documentation -- **Keep** documentation index up to date - -## Benefits - -1. **Easier Navigation**: Single index makes finding docs simple -2. **Reduced Redundancy**: No duplicate implementation summaries -3. **Better Organization**: Clear categories for different audiences -4. **Historical Preservation**: Archived files still accessible -5. **Maintainability**: Clear structure makes updates easier - -## Migration Notes - -If you have bookmarks or links to old documentation: - -- Implementation summaries → See `CHANGELOG.md` for version history -- All other docs → Same location, just better organized -- Use `docs/INDEX.md` to find any documentation - ---- - -**Consolidation Date**: 2025-01-XX -**Next Review**: As needed when documentation grows diff --git a/docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md b/docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index 07fe466..0000000 --- a/docs/archive/FINAL_IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,356 +0,0 @@ -# Complete Implementation Summary - -This document summarizes ALL critical (P0) and high-priority (P1) features that have been implemented. - -## Implementation Statistics - -- **P0 Tasks Completed**: 14 tasks -- **P1 Tasks Completed**: 12 tasks -- **Total Features Implemented**: 26 tasks -- **New Scripts Created**: 15 scripts -- **New Documentation**: 4 comprehensive guides - ---- - -## Phase 1: Core Enhancements (v1.1.0) - -### ✅ Backup & Scheduling (6 P0 tasks) - -1. **Cron-based Backup Scheduling** (`scripts/backup-scheduler.sh`) - - Configurable daily/weekly/monthly schedules - - Time-of-day configuration - - Logging system - -2. **Systemd Timer Support** (`systemd/minecraft-backup.service`, `systemd/minecraft-backup.timer`) - - Reliable systemd-based scheduling - - Persistent timers - - Easy installation script - -3. **Backup Retention Policy** (`scripts/cleanup-backups.sh`) - - Keep last N backups - - Separate retention for daily/weekly/monthly - - Automatic cleanup - -4. **Pre-backup World Save** (Enhanced `scripts/manage.sh`) - - Automatic `save-all` before backup - - Works with/without RCON - -5. **Backup Verification** (Enhanced `scripts/manage.sh`) - - Integrity checks - - File count verification - - Size reporting - -6. **Backup Compression** (Enhanced `scripts/manage.sh`) - - Optimized gzip compression - - Size reporting - -### ✅ Monitoring & Metrics (8 P0 tasks) - -1. **TPS Monitoring** (`scripts/monitor.sh`) - - Extracts TPS from logs - - CSV storage format - -2. **Memory Usage Monitoring** (`scripts/monitor.sh`) - - Docker stats integration - - Memory leak detection capability - -3. **CPU Usage Tracking** (`scripts/monitor.sh`) - - CPU percentage monitoring - - Historical tracking - -4. **Player Count Analytics** (`scripts/monitor.sh`) - - Player count over time - - Peak hours analysis capability - -5. **Server Uptime Tracking** (`scripts/monitor.sh`) - - Calculates uptime from container start - - Historical tracking - -6. **Log Aggregation** (docker-compose.yml) - - Docker log rotation - - 10MB per file, 3 files max - -7. **Health Check Endpoints** (`scripts/health-check.sh`) - - Container status - - Java process verification - - Port listening checks - - CPU/memory thresholds - -8. **Prometheus Metrics Export** (`scripts/prometheus-exporter.sh`) - - Prometheus format - - HTTP endpoint support - - All key metrics exposed - ---- - -## Phase 1: Update Management (v1.1.0) - -### ✅ Update Management (3 P1 tasks) - -1. **Automatic Version Checking** (`scripts/check-version.sh`) - - Queries Mojang API - - Compares versions - - Configurable frequency - -2. **One-Command Server Updates** (Enhanced `scripts/manage.sh`) - - Automatic backup - - Downloads new jar - - Updates configuration - - Rebuilds container - -3. **Version Compatibility Checking** (`scripts/check-compatibility.sh`) - - World compatibility - - Plugin compatibility - - Mod compatibility - - Configuration validation - ---- - -## Phase 1: Server Variants (v1.2.0) - -### ✅ Server Implementation Support (5 P1 tasks) - -1. **Server Type Selection** (`scripts/switch-server-type.sh`) - - Switch between Vanilla, Paper, Spigot, Fabric - - Automatic configuration updates - -2. **Automatic Server Jar Download** (`scripts/download-server.sh`) - - Universal downloader - - Supports Vanilla, Paper, Fabric - - Version-specific URLs - -3. **Paper Server Support** (Integrated in download-server.sh) - - PaperMC API integration - - Automatic build selection - -4. **Fabric Server Support** (Integrated in download-server.sh) - - Fabric installer integration - - Automatic server generation - -5. **Spigot Server Support** (Documented) - - BuildTools reference - - Manual build process - ---- - -## Phase 1: Plugin Management (v1.2.0) - -### ✅ Plugin Management (4 P1 tasks) - -1. **Plugin Installation System** (`scripts/plugin-manager.sh`) - - Install from .jar files - - Plugin info extraction - - Automatic backups - -2. **Plugin Update Mechanism** (`scripts/plugin-manager.sh`) - - Update with new .jar - - Configuration backup - - Version comparison - -3. **Plugin Enable/Disable** (`scripts/plugin-manager.sh`) - - Enable/disable without removal - - Disabled plugins directory - - State tracking - -4. **Plugin Configuration Management** (`scripts/plugin-config-manager.sh`) - - Configuration validation - - Backup/restore - - Template system - ---- - -## Files Created - -### Scripts (15 files) -1. `scripts/backup-scheduler.sh` - Backup scheduling -2. `scripts/cleanup-backups.sh` - Backup retention -3. `scripts/install-backup-timer.sh` - Systemd timer installer -4. `scripts/monitor.sh` - Metrics collection -5. `scripts/health-check.sh` - Health checks -6. `scripts/prometheus-exporter.sh` - Prometheus export -7. `scripts/check-version.sh` - Version checking -8. `scripts/download-server.sh` - Server downloader -9. `scripts/switch-server-type.sh` - Server type switcher -10. `scripts/check-compatibility.sh` - Compatibility checking -11. `scripts/plugin-manager.sh` - Plugin management -12. `scripts/plugin-config-manager.sh` - Plugin config management - -### Configuration Files (3 files) -1. `config/backup-schedule.conf` - Backup scheduling config -2. `config/backup-retention.conf` - Backup retention config -3. `config/update-check.conf` - Update check config - -### Systemd Files (2 files) -1. `systemd/minecraft-backup.service` - Backup service -2. `systemd/minecraft-backup.timer` - Backup timer - -### Documentation (4 files) -1. `docs/BACKUP_AND_MONITORING.md` - Backup & monitoring guide -2. `docs/UPDATE_MANAGEMENT.md` - Update management guide -3. `docs/PLUGIN_MANAGEMENT.md` - Plugin management guide -4. `IMPLEMENTATION_SUMMARY.md` - P0 features summary -5. `IMPLEMENTATION_SUMMARY_P1.md` - P1 features summary -6. `FINAL_IMPLEMENTATION_SUMMARY.md` - This file - ---- - -## Enhanced Files - -1. `scripts/manage.sh` - Added: - - Enhanced backup with save & verification - - Update server command - - Check version command - - Check compatibility command - - Plugin management integration - -2. `scripts/start.sh` - Enhanced to: - - Support SERVER_TYPE variable - - Auto-detect jar filename by server type - -3. `docker-compose.yml` - Enhanced: - - Improved healthcheck - - Plugin volume mount - -4. `README.md` - Updated: - - New features list - - New commands - - Documentation links - ---- - -## Quick Reference - -### Backup Management -```bash -./scripts/manage.sh backup # Manual backup -./scripts/backup-scheduler.sh # Run scheduled backup -./scripts/cleanup-backups.sh # Clean old backups -./scripts/install-backup-timer.sh # Install systemd timer -``` - -### Monitoring -```bash -./scripts/monitor.sh # Collect metrics -./scripts/health-check.sh # Check server health -./scripts/prometheus-exporter.sh # Export Prometheus metrics -``` - -### Updates -```bash -./scripts/manage.sh check-version # Check for updates -./scripts/manage.sh update [version] # Update server -./scripts/manage.sh check-compatibility # Check compatibility -``` - -### Server Types -```bash -./scripts/switch-server-type.sh list # List types -./scripts/switch-server-type.sh paper # Switch to Paper -./scripts/download-server.sh --type paper --version 1.21.0 -``` - -### Plugins -```bash -./scripts/manage.sh plugins list # List plugins -./scripts/manage.sh plugins install # Install plugin -./scripts/manage.sh plugins enable # Enable plugin -./scripts/manage.sh plugins disable # Disable plugin -./scripts/manage.sh plugins update # Update plugin -./scripts/plugin-config-manager.sh list # List configs -./scripts/plugin-config-manager.sh validate # Validate config -``` - ---- - -## Key Features Summary - -### Automation -- ✅ Automated backup scheduling (cron/systemd) -- ✅ Automatic backup retention cleanup -- ✅ Automatic version checking -- ✅ One-command server updates - -### Monitoring -- ✅ Real-time metrics collection -- ✅ Health check endpoints -- ✅ Prometheus metrics export -- ✅ Performance tracking (TPS, CPU, Memory) - -### Management -- ✅ Multiple server types (Vanilla, Paper, Spigot, Fabric) -- ✅ Plugin installation & management -- ✅ Configuration management -- ✅ Update management with compatibility checks - -### Reliability -- ✅ Backup verification -- ✅ Pre-backup world saves -- ✅ Configuration backups -- ✅ Rollback capabilities - ---- - -## Testing Status - -All scripts have been created with: -- Error handling -- Input validation -- User-friendly output -- Comprehensive logging -- Documentation - -**Recommended Testing:** -1. Test backup scheduling on Raspberry Pi -2. Test server type switching -3. Test plugin installation -4. Test update process -5. Verify monitoring metrics collection - ---- - -## Next Steps - -### Remaining P1 Tasks -- None! All P1 tasks are complete. - -### P2 Tasks (Medium Priority) -- Multi-world support -- Advanced server management (RCON, API) -- Dynamic DNS integration -- Cloud backup integration - -### Future Enhancements -- Web admin panel (v1.4.0) -- Mobile app (v1.6.0) -- Multi-server orchestration (v2.0.0) - ---- - -## Documentation - -All features are documented in: -- `docs/BACKUP_AND_MONITORING.md` -- `docs/UPDATE_MANAGEMENT.md` -- `docs/PLUGIN_MANAGEMENT.md` -- `README.md` (updated with all new features) - ---- - -## Conclusion - -**26 critical and high-priority features have been successfully implemented**, providing: - -1. **Complete backup automation** with scheduling and retention -2. **Comprehensive monitoring** with metrics and health checks -3. **Easy update management** with compatibility checking -4. **Multiple server type support** with automatic downloads -5. **Full plugin management** with configuration handling - -The Minecraft server setup is now production-ready with enterprise-grade features for automation, monitoring, and management. - ---- - -**Implementation Date**: 2025-01-XX -**Total Development Time**: Comprehensive feature set -**Status**: ✅ All P0 and P1 tasks complete - diff --git a/docs/archive/GAMEPLAY_FEATURES_IMPLEMENTED.md b/docs/archive/GAMEPLAY_FEATURES_IMPLEMENTED.md deleted file mode 100644 index 2c0ba97..0000000 --- a/docs/archive/GAMEPLAY_FEATURES_IMPLEMENTED.md +++ /dev/null @@ -1,221 +0,0 @@ -# Gameplay Features Implementation Summary - -This document summarizes the three high-priority gameplay features that have been implemented. - -## ✅ Completed Features - -### 1. Enhanced Command Scheduler ✅ - -**Status**: Complete -**File**: `scripts/command-scheduler.py` -**API Endpoints**: `/api/commands/schedules`, `/api/commands/schedule`, etc. - -#### Features Added: - -- **Cron Expression Support**: Full cron syntax for flexible scheduling -- **Conditional Execution**: Run commands based on: - - Player count thresholds (e.g., only if > 5 players) - - Time ranges (peak hours) - - Day of week filters -- **Multiple Schedule Types**: - - `interval` - Run every X minutes/hours - - `daily` - Run at specific time daily - - `weekly` - Run on specific day at specific time - - `cron` - Full cron expression support - - `once` - Run once at specific datetime -- **Command Templates**: Variables like `{time}`, `{date}`, `{player_count}`, `{datetime}` -- **Schedule Management**: Enable/disable, list, create, delete schedules - -#### Usage Examples: - -```bash -# Create a daily announcement at 6 PM -./scripts/command-scheduler.py add "say Peak hours!" daily --run_time "18:00" - -# Create conditional command (only if > 5 players) -# Via API: POST /api/commands/schedule with condition - -# Create cron schedule (every hour at minute 0) -./scripts/command-scheduler.py add "say Hourly reminder" cron --cron_expression "0 * * * *" -``` - -#### API Endpoints: - -- `GET /api/commands/schedules` - List all schedules -- `POST /api/commands/schedule` - Create new schedule -- `DELETE /api/commands/schedule/` - Delete schedule -- `PUT /api/commands/schedule//enable` - Enable schedule -- `PUT /api/commands/schedule//disable` - Disable schedule - ---- - -### 2. Player Statistics Tracker ✅ - -**Status**: Complete -**File**: `scripts/player-stats-tracker.sh` -**API Endpoints**: `/api/players/stats`, `/api/players/stats/`, etc. - -#### Features Added: - -- **Player Tracking**: Automatic tracking from server logs -- **Statistics Collected**: - - Login/logout counts - - Play time (session tracking) - - Death count - - Blocks broken/placed - - First seen / Last seen timestamps -- **Leaderboards**: Top players by any metric -- **Log Parsing**: Automatic parsing of server logs for player events -- **JSON Storage**: All stats stored in JSON format - -#### Usage Examples: - -```bash -# Parse server logs for player events -./scripts/player-stats-tracker.sh parse - -# Get player statistics -./scripts/player-stats-tracker.sh get PlayerName - -# Get leaderboard (top 10 by login count) -./scripts/player-stats-tracker.sh leaderboard login_count 10 - -# Update player stat manually -./scripts/player-stats-tracker.sh update PlayerName blocks_broken 100 -``` - -#### API Endpoints: - -- `GET /api/players/stats` - Get all player statistics -- `GET /api/players/stats/` - Get specific player stats -- `GET /api/players/stats/leaderboard?metric=&limit=` - Get leaderboard -- `POST /api/players/stats/parse` - Parse server logs for stats - -#### Statistics Tracked: - -- `login_count` - Number of times player logged in -- `logout_count` - Number of times player logged out -- `deaths` - Number of deaths -- `blocks_broken` - Blocks broken -- `blocks_placed` - Blocks placed -- `first_seen` - First seen timestamp -- `last_seen` - Last seen timestamp - ---- - -### 3. Announcement System ✅ - -**Status**: Complete -**File**: `scripts/announcement-manager.sh` -**API Endpoints**: `/api/announcements`, etc. - -#### Features Added: - -- **Multiple Announcement Types**: - - `say` - Chat message - - `title` - Title text - - `subtitle` - Subtitle text - - `actionbar` - Actionbar message -- **Scheduled Announcements**: Support for daily/weekly schedules -- **Storage**: JSON-based storage for announcements -- **Immediate Send**: Send announcements immediately via API -- **Management**: Create, list, send, delete announcements - -#### Usage Examples: - -```bash -# Create simple announcement -./scripts/announcement-manager.sh create "Welcome to our server!" say - -# Create scheduled title announcement -./scripts/announcement-manager.sh create \ - "Server restart in 10 minutes" \ - title \ - daily \ - "02:50" - -# Send announcement immediately -./scripts/announcement-manager.sh send - -# List all announcements -./scripts/announcement-manager.sh list - -# Delete announcement -./scripts/announcement-manager.sh delete -``` - -#### API Endpoints: - -- `GET /api/announcements` - List all announcements -- `POST /api/announcements` - Create new announcement -- `POST /api/announcements//send` - Send announcement immediately -- `DELETE /api/announcements/` - Delete announcement - -#### Request Body Example: - -```json -{ - "message": "Welcome to our server!", - "type": "title", - "schedule_type": "daily", - "schedule_time": "12:00", - "enabled": true -} -``` - ---- - -## Integration Points - -All features integrate with: - -1. **RCON**: Commands executed via RCON client -2. **REST API**: Full API access for web interface -3. **Web UI**: Ready for React component integration -4. **Logging**: Comprehensive logging and audit trails -5. **Permissions**: RBAC permission system - -## Configuration Files - -- **Command Schedules**: `config/command-schedule.json` -- **Player Stats**: `data/stats/player-stats.json` -- **Announcements**: `config/announcements.json` - -## Dependencies - -### Required: - -- Python 3.x -- Bash 4.x+ -- RCON client (via rcon-client.sh) - -### Optional: - -- `croniter` (for cron expression support) - Added to `api/requirements.txt` - -## Next Steps - -These features are now ready for: - -1. **Web UI Integration**: Create React components for: - - - Command scheduler management UI - - Player statistics dashboard - - Announcement management interface - -2. **Testing**: Create test cases for: - - - Command scheduler execution - - Player stats tracking - - Announcement delivery - -3. **Documentation**: Add to main documentation: - - User guide for command scheduling - - Player statistics guide - - Announcement system guide - -## See Also - -- [Minecraft Gameplay Enhancements](MINECRAFT_GAMEPLAY_ENHANCEMENTS.md) - Full enhancement roadmap -- [API Documentation](API.md) - Complete API reference -- [Web Interface Guide](WEB_INTERFACE.md) - Web UI integration diff --git a/docs/archive/IMPLEMENTATION_SUMMARY.md b/docs/archive/IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index 1f712e9..0000000 --- a/docs/archive/IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,262 +0,0 @@ -# Critical Features Implementation Summary - -This document summarizes the critical P0 features that have been implemented. - -## Completed Features (P0 - Critical) - -### Backup & Scheduling ✅ - -#### 1. Cron-based Backup Scheduling (Task 1.1.1) - -- **File**: `scripts/backup-scheduler.sh` -- **Config**: `config/backup-schedule.conf` -- **Features**: - - Supports daily, weekly, and monthly schedules - - Configurable time-of-day execution - - Logging to `logs/backup-scheduler.log` - - Automatic cleanup integration - -#### 2. Systemd Timer for Backups (Task 1.1.2) - -- **Files**: - - `systemd/minecraft-backup.service` - - `systemd/minecraft-backup.timer` - - `scripts/install-backup-timer.sh` -- **Features**: - - Systemd-based scheduling (more reliable than cron) - - Runs daily at 3:00 AM by default - - Persistent timers (runs missed backups on boot) - - Easy installation script - -#### 3. Backup Retention Policy (Task 1.1.3) - -- **File**: `scripts/cleanup-backups.sh` -- **Config**: `config/backup-retention.conf` -- **Features**: - - Keep last N backups regardless of age - - Separate retention for daily/weekly/monthly backups - - Automatic classification of backup types - - Size reporting after cleanup - -#### 4. Pre-backup World Save (Task 1.1.4) - -- **File**: `scripts/manage.sh` (enhanced `create_backup()`) -- **Features**: - - Automatically executes `save-all` before backup - - Works with or without RCON - - Waits for save completion - - Error handling - -#### 5. Backup Verification (Task 1.1.5) - -- **File**: `scripts/manage.sh` (enhanced `create_backup()`) -- **Features**: - - Verifies backup integrity using tar test - - Counts files in backup - - Reports backup size - - Fails if verification fails - -#### 6. Backup Compression (Task 1.1.6) - -- **File**: `scripts/manage.sh` (enhanced `create_backup()`) -- **Features**: - - Uses gzip compression (tar.gz) - - Reports compressed size - - Can be extended for other compression algorithms - -### Monitoring & Metrics ✅ - -#### 7. TPS Monitoring (Task 1.2.1) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Extracts TPS from server logs - - Stores TPS history in CSV format - - Logs to `metrics/tps.csv` - -#### 8. Memory Usage Monitoring (Task 1.2.2) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Tracks memory usage via Docker stats - - Records memory consumption over time - - Logs to `metrics/memory_usage.csv` - - Can detect memory leaks (via trend analysis) - -#### 9. CPU Usage Tracking (Task 1.2.3) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Monitors CPU usage percentage - - Tracks CPU over time - - Logs to `metrics/cpu_usage.csv` - - Can be extended for per-core tracking - -#### 10. Player Count Analytics (Task 1.2.4) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Tracks player count over time - - Extracts from server logs - - Logs to `metrics/player_count.csv` - - Can be used for peak hours analysis - -#### 11. Server Uptime Tracking (Task 1.2.5) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Calculates uptime from container start time - - Tracks uptime in seconds - - Logs to `metrics/server_uptime.csv` - -#### 12. Log Aggregation (Task 1.2.6) - -- **Features**: - - Docker logging with rotation (configured in docker-compose.yml) - - Logs stored in Docker's JSON log driver - - Max size: 10MB per file - - Max files: 3 (30MB total) - -#### 13. Health Check Endpoints (Task 1.2.7) - -- **File**: `scripts/health-check.sh` -- **Features**: - - Checks container status - - Verifies Java process - - Checks port listening - - Monitors CPU and memory thresholds - - Returns exit codes for automation - - Integrated into docker-compose.yml healthcheck - -#### 14. Prometheus Metrics Export (Task 1.2.8) - -- **File**: `scripts/prometheus-exporter.sh` -- **Features**: - - Exports metrics in Prometheus format - - HTTP endpoint support (port 9091) - - All key metrics exposed - - Ready for Grafana integration - -## New Files Created - -### Scripts - -1. `scripts/backup-scheduler.sh` - Cron/systemd backup scheduler -2. `scripts/cleanup-backups.sh` - Backup retention cleanup -3. `scripts/install-backup-timer.sh` - Systemd timer installer -4. `scripts/monitor.sh` - Metrics collection script -5. `scripts/health-check.sh` - Health check script -6. `scripts/prometheus-exporter.sh` - Prometheus metrics exporter - -### Configuration Files - -1. `config/backup-schedule.conf` - Backup scheduling configuration -2. `config/backup-retention.conf` - Backup retention policy - -### Systemd Files - -1. `systemd/minecraft-backup.service` - Systemd service file -2. `systemd/minecraft-backup.timer` - Systemd timer file - -### Documentation - -1. `docs/BACKUP_AND_MONITORING.md` - Comprehensive backup & monitoring guide - -## Enhanced Files - -1. `scripts/manage.sh` - Enhanced backup function with: - - Pre-backup world save - - Backup verification - - Better error handling - - Improved RCON command sending - -2. `docker-compose.yml` - Enhanced healthcheck configuration - -3. `docs/QUICK_REFERENCE.md` - Added new commands - -4. `README.md` - Updated features list and backup section - -## Usage Examples - -### Setup Automated Backups - -```bash -# Install systemd timer -./scripts/install-backup-timer.sh - -# Or configure cron -crontab -e -# Add: 0 3 * * * /path/to/minecraft-server/scripts/backup-scheduler.sh -``` - -### Run Monitoring - -```bash -# Collect metrics once -./scripts/monitor.sh - -# Set up periodic monitoring (every 5 minutes) -*/5 * * * * /path/to/minecraft-server/scripts/monitor.sh -``` - -### Check Server Health - -```bash -# Run health check -./scripts/health-check.sh - -# Use in monitoring -if ./scripts/health-check.sh; then - echo "Server healthy" -fi -``` - -### Export Prometheus Metrics - -```bash -# Output metrics -./scripts/prometheus-exporter.sh - -# Serve on HTTP (requires netcat or HTTP server) -./scripts/prometheus-exporter.sh --serve -``` - -## Next Steps - -The following P0 tasks are now complete. Remaining P0 tasks from TASKS.md: - -- ✅ All Backup & Scheduling tasks (1.1.1 - 1.1.6) -- ✅ All Monitoring & Metrics tasks (1.2.1 - 1.2.8) - -**Next Priority Tasks (P1):** - -- Update Management (Tasks 1.3.1 - 1.3.3) -- Server Variants & Plugins (Tasks 2.1.1 - 2.2.4) - -## Testing Recommendations - -1. **Backup Testing**: - - Test manual backup: `./scripts/manage.sh backup` - - Test scheduler: `./scripts/backup-scheduler.sh` - - Test cleanup: `./scripts/cleanup-backups.sh` - - Verify backups can be restored - -2. **Monitoring Testing**: - - Run monitor script: `./scripts/monitor.sh` - - Check metrics files in `metrics/` directory - - Test health check: `./scripts/health-check.sh` - - Test Prometheus exporter: `./scripts/prometheus-exporter.sh` - -3. **Systemd Timer Testing**: - - Install timer: `./scripts/install-backup-timer.sh` - - Check status: `sudo systemctl status minecraft-backup.timer` - - Test run: `sudo systemctl start minecraft-backup.service` - - Check logs: `sudo journalctl -u minecraft-backup.service` - -## Notes - -- All scripts are designed to work on Linux/Raspberry Pi OS -- Scripts use bash and require standard Unix utilities -- Configuration files use simple shell variable syntax -- Metrics are stored in CSV format for easy analysis -- Health checks return proper exit codes for automation diff --git a/docs/archive/IMPLEMENTATION_SUMMARY_P1.md b/docs/archive/IMPLEMENTATION_SUMMARY_P1.md deleted file mode 100644 index 6b12e7d..0000000 --- a/docs/archive/IMPLEMENTATION_SUMMARY_P1.md +++ /dev/null @@ -1,275 +0,0 @@ -# P1 Features Implementation Summary - -This document summarizes the P1 (High Priority) features that have been implemented. - -## Completed Features (P1 - High Priority) - -### Update Management ✅ - -#### 1. Automatic Version Checking (Task 1.3.1) - -- **File**: `scripts/check-version.sh` -- **Config**: `config/update-check.conf` -- **Features**: - - Queries Mojang version manifest API - - Compares current vs latest version - - Configurable check frequency - - Notification system - - Integrated into `manage.sh check-version` - -#### 2. One-Command Server Updates (Task 1.3.2) - -- **File**: `scripts/manage.sh` (enhanced `update_server()`) -- **Features**: - - Automatic backup before update - - Downloads new server jar - - Updates docker-compose.yml - - Rebuilds container - - Restarts server - - Rollback capability via backups - - Usage: `./manage.sh update [version]` - -#### 3. Version Compatibility Checking (Task 1.3.3) - -- **File**: `scripts/check-compatibility.sh` -- **Features**: - - Checks world compatibility - - Verifies plugin compatibility - - Checks mod compatibility - - Validates configuration files - - Detects major vs minor version changes - - Integrated into update process - - Usage: `./manage.sh check-compatibility ` - -### Server Variants & Download ✅ - -#### 4. Server Type Selection System (Task 2.1.4) - -- **File**: `scripts/switch-server-type.sh` -- **Features**: - - Switch between Vanilla, Paper, Spigot, Fabric - - Lists available types - - Shows current type - - Updates docker-compose.yml automatically - - Downloads server jar if needed - - Usage: `./switch-server-type.sh ` - -#### 5. Automatic Server Jar Download (Task 2.1.5) - -- **File**: `scripts/download-server.sh` -- **Features**: - - Supports Vanilla, Paper, Fabric - - Version-specific URLs - - Download verification - - Automatic file naming - - Error handling - - Usage: `./download-server.sh --type --version ` - -#### 6. Paper Server Support (Task 2.1.1) - -- **Implementation**: Integrated into download-server.sh -- **Features**: - - Queries PaperMC API - - Downloads latest Paper build for version - - Automatic jar naming - - Ready for use with SERVER_TYPE=paper - -#### 7. Fabric Server Support (Task 2.1.3) - -- **Implementation**: Integrated into download-server.sh -- **Features**: - - Downloads Fabric installer - - Runs installer automatically - - Generates Fabric server jar - - Ready for use with SERVER_TYPE=fabric - -#### 8. Spigot Server Support (Task 2.1.2) - -- **Status**: Partial (requires BuildTools) -- **Implementation**: Noted in download-server.sh -- **Note**: Spigot requires BuildTools to build from source -- **Documentation**: References provided - -## New Files Created - -### Scripts - -1. `scripts/check-version.sh` - Version checking script -2. `scripts/download-server.sh` - Universal server downloader -3. `scripts/switch-server-type.sh` - Server type switcher -4. `scripts/check-compatibility.sh` - Compatibility checker - -### Configuration Files - -1. `config/update-check.conf` - Update check configuration - -### Documentation - -1. `docs/UPDATE_MANAGEMENT.md` - Comprehensive update management guide - -## Enhanced Files - -1. `scripts/manage.sh` - Added: - - `update_server()` function - - `check-version` command - - `check-compatibility` command - - Integration with compatibility checking - -2. `scripts/start.sh` - Enhanced to: - - Support SERVER_TYPE environment variable - - Auto-detect jar filename based on server type - - Support Paper, Fabric, Spigot jar naming - -3. `README.md` - Updated with: - - New commands - - Server type information - - Update management features - -## Usage Examples - -### Check for Updates - -```bash -# Check if updates are available -./scripts/manage.sh check-version - -# Or use script directly -./scripts/check-version.sh -``` - -### Update Server - -```bash -# Update to latest version -./scripts/manage.sh update - -# Update to specific version -./scripts/manage.sh update 1.21.0 - -# Check compatibility first -./scripts/manage.sh check-compatibility 1.21.0 -``` - -### Switch Server Type - -```bash -# List available types -./scripts/switch-server-type.sh list - -# Check current type -./scripts/switch-server-type.sh current - -# Switch to Paper -./scripts/switch-server-type.sh paper - -# Switch to Fabric -./scripts/switch-server-type.sh fabric - -# Switch back to Vanilla -./scripts/switch-server-type.sh vanilla -``` - -### Download Server Jars - -```bash -# Download Vanilla -./scripts/download-server.sh --type vanilla --version 1.21.0 - -# Download Paper -./scripts/download-server.sh --type paper --version 1.21.0 - -# Download Fabric -./scripts/download-server.sh --type fabric --version 1.21.0 -``` - -## Integration Points - -### Docker Compose - -Server type is configured via environment variable: - -```yaml -environment: - - SERVER_TYPE=paper # vanilla, paper, spigot, or fabric -``` - -### Start Script - -The start script automatically detects the server type and uses the appropriate jar file. - -### Update Process - -The update process: - -1. Checks compatibility -2. Creates backup -3. Downloads new jar -4. Updates configuration -5. Rebuilds container -6. Restarts server - -## API Integrations - -### Mojang Version Manifest API - -- **URL**: `https://launchermeta.mojang.com/mc/game/version_manifest.json` -- **Used for**: Getting latest versions and download URLs - -### PaperMC API - -- **URL**: `https://api.papermc.io/v2/projects/paper/versions/{version}` -- **Used for**: Getting Paper builds and download URLs - -### Fabric API - -- **URL**: `https://meta.fabricmc.net/v2/versions/installer` -- **Used for**: Getting Fabric installer versions - -## Testing Recommendations - -1. **Version Checking**: - - ```bash - ./scripts/check-version.sh - ``` - -2. **Compatibility Checking**: - - ```bash - ./scripts/check-compatibility.sh 1.21.0 - ``` - -3. **Server Type Switching**: - - ```bash - ./scripts/switch-server-type.sh paper - ./scripts/manage.sh start - ``` - -4. **Update Process**: - - ```bash - # Test update to a test version first - ./scripts/manage.sh update 1.20.5 - ``` - -## Notes - -- All scripts require internet connection for API queries -- Paper and Fabric downloads require valid version numbers -- Spigot requires BuildTools (not automated) -- Compatibility checking provides warnings, not hard blocks -- Backups are automatically created before updates -- Server type switching stops the server if running - -## Next Steps - -Remaining P1 tasks: - -- Plugin Management (Tasks 2.2.1 - 2.2.4) - - Plugin installation system - - Plugin update mechanism - - Plugin enable/disable - - Plugin configuration management - -These can be implemented next if needed. diff --git a/docs/archive/IMPLEMENTATION_SUMMARY_docs.md b/docs/archive/IMPLEMENTATION_SUMMARY_docs.md deleted file mode 100644 index 1f712e9..0000000 --- a/docs/archive/IMPLEMENTATION_SUMMARY_docs.md +++ /dev/null @@ -1,262 +0,0 @@ -# Critical Features Implementation Summary - -This document summarizes the critical P0 features that have been implemented. - -## Completed Features (P0 - Critical) - -### Backup & Scheduling ✅ - -#### 1. Cron-based Backup Scheduling (Task 1.1.1) - -- **File**: `scripts/backup-scheduler.sh` -- **Config**: `config/backup-schedule.conf` -- **Features**: - - Supports daily, weekly, and monthly schedules - - Configurable time-of-day execution - - Logging to `logs/backup-scheduler.log` - - Automatic cleanup integration - -#### 2. Systemd Timer for Backups (Task 1.1.2) - -- **Files**: - - `systemd/minecraft-backup.service` - - `systemd/minecraft-backup.timer` - - `scripts/install-backup-timer.sh` -- **Features**: - - Systemd-based scheduling (more reliable than cron) - - Runs daily at 3:00 AM by default - - Persistent timers (runs missed backups on boot) - - Easy installation script - -#### 3. Backup Retention Policy (Task 1.1.3) - -- **File**: `scripts/cleanup-backups.sh` -- **Config**: `config/backup-retention.conf` -- **Features**: - - Keep last N backups regardless of age - - Separate retention for daily/weekly/monthly backups - - Automatic classification of backup types - - Size reporting after cleanup - -#### 4. Pre-backup World Save (Task 1.1.4) - -- **File**: `scripts/manage.sh` (enhanced `create_backup()`) -- **Features**: - - Automatically executes `save-all` before backup - - Works with or without RCON - - Waits for save completion - - Error handling - -#### 5. Backup Verification (Task 1.1.5) - -- **File**: `scripts/manage.sh` (enhanced `create_backup()`) -- **Features**: - - Verifies backup integrity using tar test - - Counts files in backup - - Reports backup size - - Fails if verification fails - -#### 6. Backup Compression (Task 1.1.6) - -- **File**: `scripts/manage.sh` (enhanced `create_backup()`) -- **Features**: - - Uses gzip compression (tar.gz) - - Reports compressed size - - Can be extended for other compression algorithms - -### Monitoring & Metrics ✅ - -#### 7. TPS Monitoring (Task 1.2.1) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Extracts TPS from server logs - - Stores TPS history in CSV format - - Logs to `metrics/tps.csv` - -#### 8. Memory Usage Monitoring (Task 1.2.2) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Tracks memory usage via Docker stats - - Records memory consumption over time - - Logs to `metrics/memory_usage.csv` - - Can detect memory leaks (via trend analysis) - -#### 9. CPU Usage Tracking (Task 1.2.3) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Monitors CPU usage percentage - - Tracks CPU over time - - Logs to `metrics/cpu_usage.csv` - - Can be extended for per-core tracking - -#### 10. Player Count Analytics (Task 1.2.4) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Tracks player count over time - - Extracts from server logs - - Logs to `metrics/player_count.csv` - - Can be used for peak hours analysis - -#### 11. Server Uptime Tracking (Task 1.2.5) - -- **File**: `scripts/monitor.sh` -- **Features**: - - Calculates uptime from container start time - - Tracks uptime in seconds - - Logs to `metrics/server_uptime.csv` - -#### 12. Log Aggregation (Task 1.2.6) - -- **Features**: - - Docker logging with rotation (configured in docker-compose.yml) - - Logs stored in Docker's JSON log driver - - Max size: 10MB per file - - Max files: 3 (30MB total) - -#### 13. Health Check Endpoints (Task 1.2.7) - -- **File**: `scripts/health-check.sh` -- **Features**: - - Checks container status - - Verifies Java process - - Checks port listening - - Monitors CPU and memory thresholds - - Returns exit codes for automation - - Integrated into docker-compose.yml healthcheck - -#### 14. Prometheus Metrics Export (Task 1.2.8) - -- **File**: `scripts/prometheus-exporter.sh` -- **Features**: - - Exports metrics in Prometheus format - - HTTP endpoint support (port 9091) - - All key metrics exposed - - Ready for Grafana integration - -## New Files Created - -### Scripts - -1. `scripts/backup-scheduler.sh` - Cron/systemd backup scheduler -2. `scripts/cleanup-backups.sh` - Backup retention cleanup -3. `scripts/install-backup-timer.sh` - Systemd timer installer -4. `scripts/monitor.sh` - Metrics collection script -5. `scripts/health-check.sh` - Health check script -6. `scripts/prometheus-exporter.sh` - Prometheus metrics exporter - -### Configuration Files - -1. `config/backup-schedule.conf` - Backup scheduling configuration -2. `config/backup-retention.conf` - Backup retention policy - -### Systemd Files - -1. `systemd/minecraft-backup.service` - Systemd service file -2. `systemd/minecraft-backup.timer` - Systemd timer file - -### Documentation - -1. `docs/BACKUP_AND_MONITORING.md` - Comprehensive backup & monitoring guide - -## Enhanced Files - -1. `scripts/manage.sh` - Enhanced backup function with: - - Pre-backup world save - - Backup verification - - Better error handling - - Improved RCON command sending - -2. `docker-compose.yml` - Enhanced healthcheck configuration - -3. `docs/QUICK_REFERENCE.md` - Added new commands - -4. `README.md` - Updated features list and backup section - -## Usage Examples - -### Setup Automated Backups - -```bash -# Install systemd timer -./scripts/install-backup-timer.sh - -# Or configure cron -crontab -e -# Add: 0 3 * * * /path/to/minecraft-server/scripts/backup-scheduler.sh -``` - -### Run Monitoring - -```bash -# Collect metrics once -./scripts/monitor.sh - -# Set up periodic monitoring (every 5 minutes) -*/5 * * * * /path/to/minecraft-server/scripts/monitor.sh -``` - -### Check Server Health - -```bash -# Run health check -./scripts/health-check.sh - -# Use in monitoring -if ./scripts/health-check.sh; then - echo "Server healthy" -fi -``` - -### Export Prometheus Metrics - -```bash -# Output metrics -./scripts/prometheus-exporter.sh - -# Serve on HTTP (requires netcat or HTTP server) -./scripts/prometheus-exporter.sh --serve -``` - -## Next Steps - -The following P0 tasks are now complete. Remaining P0 tasks from TASKS.md: - -- ✅ All Backup & Scheduling tasks (1.1.1 - 1.1.6) -- ✅ All Monitoring & Metrics tasks (1.2.1 - 1.2.8) - -**Next Priority Tasks (P1):** - -- Update Management (Tasks 1.3.1 - 1.3.3) -- Server Variants & Plugins (Tasks 2.1.1 - 2.2.4) - -## Testing Recommendations - -1. **Backup Testing**: - - Test manual backup: `./scripts/manage.sh backup` - - Test scheduler: `./scripts/backup-scheduler.sh` - - Test cleanup: `./scripts/cleanup-backups.sh` - - Verify backups can be restored - -2. **Monitoring Testing**: - - Run monitor script: `./scripts/monitor.sh` - - Check metrics files in `metrics/` directory - - Test health check: `./scripts/health-check.sh` - - Test Prometheus exporter: `./scripts/prometheus-exporter.sh` - -3. **Systemd Timer Testing**: - - Install timer: `./scripts/install-backup-timer.sh` - - Check status: `sudo systemctl status minecraft-backup.timer` - - Test run: `sudo systemctl start minecraft-backup.service` - - Check logs: `sudo journalctl -u minecraft-backup.service` - -## Notes - -- All scripts are designed to work on Linux/Raspberry Pi OS -- Scripts use bash and require standard Unix utilities -- Configuration files use simple shell variable syntax -- Metrics are stored in CSV format for easy analysis -- Health checks return proper exit codes for automation diff --git a/docs/archive/README.md b/docs/archive/README.md deleted file mode 100644 index 6a5429f..0000000 --- a/docs/archive/README.md +++ /dev/null @@ -1,47 +0,0 @@ -# Archive Directory - -This directory contains archived documentation files that have been consolidated or superseded. - -## Archived Files - -### Implementation Summaries - -- `IMPLEMENTATION_SUMMARY.md` - Consolidated into CHANGELOG.md -- `IMPLEMENTATION_SUMMARY_P1.md` - Consolidated into CHANGELOG.md -- `FINAL_IMPLEMENTATION_SUMMARY.md` - Consolidated into CHANGELOG.md -- `IMPLEMENTATION_SUMMARY_docs.md` - Consolidated into CHANGELOG.md - -These files documented feature implementations but have been consolidated into the main CHANGELOG.md for better organization. - -### Consolidated Documentation - -The following files have been consolidated into comprehensive guides: - -- `CI_CD_PIPELINE.md` → Consolidated into [CI_CD.md](../CI_CD.md) -- `CI_CD_OPTIMIZATIONS.md` → Consolidated into [CI_CD.md](../CI_CD.md) -- `CI_CD_ENHANCEMENTS.md` → Consolidated into [CI_CD.md](../CI_CD.md) -- `API_DOCUMENTATION.md` → Consolidated into [API.md](../API.md) -- `TESTING_COMPLETE.md` → Consolidated into [TESTING.md](../TESTING.md) -- `TESTING_FINAL_SUMMARY.md` → Consolidated into [TESTING.md](../TESTING.md) -- `TESTING_ENHANCEMENTS.md` → Consolidated into [TESTING.md](../TESTING.md) -- `GAMEPLAY_FEATURES_IMPLEMENTED.md` → Consolidated into [MINECRAFT_GAMEPLAY_ENHANCEMENTS.md](../MINECRAFT_GAMEPLAY_ENHANCEMENTS.md) and [CHANGELOG.md](../../CHANGELOG.md) -- `SUMMARY.md` → Information available in [CHANGELOG.md](../../CHANGELOG.md), [ROADMAP.md](../ROADMAP.md), and [INDEX.md](../INDEX.md) -- `CONSOLIDATION_NOTES.md` → Historical record of documentation consolidation - -### Summary and Checklist Files - -- `RPI5_OPTIMIZATIONS_SUMMARY.md` → Quick reference (may be integrated later) -- `RPI5_ACTION_CHECKLIST.md` → Verification checklist (may be integrated later) - -## Current Documentation - -For current documentation, see: - -- **[docs/INDEX.md](../INDEX.md)** - Documentation index and navigation -- **[docs/README.md](../README.md)** - Documentation structure guide -- **[CHANGELOG.md](../../CHANGELOG.md)** - Version history and changes -- **[README.md](../../README.md)** - Main project documentation - -## Note - -Archived files are preserved for historical reference but are no longer actively maintained. All information from archived files has been integrated into the current documentation structure. diff --git a/docs/archive/RPI5_ACTION_CHECKLIST.md b/docs/archive/RPI5_ACTION_CHECKLIST.md deleted file mode 100644 index a829f92..0000000 --- a/docs/archive/RPI5_ACTION_CHECKLIST.md +++ /dev/null @@ -1,140 +0,0 @@ -# Raspberry Pi 5 Compatibility - Action Checklist - -Quick checklist of steps needed to ensure the project runs on Raspberry Pi 5. - -## ✅ Completed - -- [x] Dockerfile uses ARM64 base image (`arm64v8/openjdk:21-jdk-slim`) -- [x] Docker Compose platform specification added (`platform: linux/arm64`) -- [x] Setup script updated to install Node.js -- [x] Setup script updated to install Python dependencies -- [x] Compatibility guide created - -## ⚠️ Needs Verification on Actual Hardware - -### Critical Verification - -- [ ] **Docker Image Build**: Build Docker image on Raspberry Pi 5 - - ```bash - docker-compose build - ``` - - Expected: Build completes without errors - -- [ ] **Server Startup**: Start Minecraft server - - ```bash - ./scripts/manage.sh start - ``` - - Expected: Server starts and is accessible - -- [ ] **Python API**: Install and test Python API dependencies - - ```bash - cd api - python3 -m venv venv - source venv/bin/activate - pip install -r requirements.txt - ``` - - Expected: All packages install successfully - -- [ ] **Node.js Web**: Install and build web interface - - ```bash - cd web - npm install - npm run build - ``` - - Expected: Build completes successfully - -- [ ] **Integration Test**: Run full test suite - - ```bash - python3 -m pytest tests/api/ -v - ``` - - Expected: All tests pass - -### Performance Verification - -- [ ] **Memory Usage**: Verify memory usage is within limits - - ```bash - docker stats minecraft-server - ``` - - Expected: Memory usage stays within configured limits - -- [ ] **CPU Usage**: Monitor CPU usage during gameplay - - ```bash - htop - ``` - - Expected: CPU usage is reasonable (<80% average) - -- [ ] **Temperature**: Monitor CPU temperature - - ```bash - vcgencmd measure_temp - ``` - - Expected: Temperature stays below 80°C under load - -## 📝 Documentation Updates Needed - -- [ ] Update README with ARM64 build instructions -- [ ] Add troubleshooting section for ARM64-specific issues -- [ ] Document performance benchmarks on Pi 5 -- [ ] Add CI/CD testing for ARM64 (optional) - -## 🔧 Optional Enhancements - -- [ ] Add architecture detection to scripts -- [ ] Create ARM64-specific optimizations -- [ ] Add multi-architecture Docker image support -- [ ] Set up automated testing on ARM64 hardware - -## Quick Test Commands - -Run these on Raspberry Pi 5 to verify everything works: - -```bash -# 1. Check architecture -uname -m # Should show: aarch64 - -# 2. Check Docker -docker info | grep Architecture # Should show: aarch64 - -# 3. Build image -docker-compose build - -# 4. Start server -./scripts/manage.sh start - -# 5. Check status -./scripts/manage.sh status - -# 6. Test API (if running) -curl http://localhost:8080/api/health - -# 7. Test web interface (if running) -curl http://localhost:3000 -``` - -## Next Steps - -1. **Test on actual Raspberry Pi 5 hardware** -2. **Document any issues found** -3. **Update compatibility guide with findings** -4. **Add performance benchmarks** -5. **Update documentation with Pi-specific notes** - ---- - -**Status**: Ready for testing on hardware -**Last Updated**: 2025-01-27 diff --git a/docs/archive/RPI5_OPTIMIZATIONS_SUMMARY.md b/docs/archive/RPI5_OPTIMIZATIONS_SUMMARY.md deleted file mode 100644 index ccca2db..0000000 --- a/docs/archive/RPI5_OPTIMIZATIONS_SUMMARY.md +++ /dev/null @@ -1,257 +0,0 @@ -# Raspberry Pi 5 Optimizations - Quick Summary - -Quick reference for all optimizations and enhancements available for Raspberry Pi 5. - -## 🚀 Quick Start - -### Apply All Optimizations - -```bash -# Run the optimization script -chmod +x scripts/optimize-rpi5.sh -./scripts/optimize-rpi5.sh -``` - -### Monitor Performance - -```bash -# Run the enhanced monitor -chmod +x scripts/monitor-rpi5.sh -./scripts/monitor-rpi5.sh -``` - -## 📋 Optimization Categories - -### 1. System-Level Optimizations - -- ✅ **CPU Governor**: Set to performance mode -- ✅ **Swap Optimization**: Reduce swap for 4GB Pi -- ✅ **Kernel Parameters**: Network and memory tuning -- ✅ **TRIM**: Enable for SD card longevity -- ✅ **Service Management**: Disable unnecessary services - -**Script**: `scripts/optimize-rpi5.sh` - -### 2. JVM Optimizations - -Enhanced JVM flags in `scripts/start.sh`: - -- ✅ String deduplication -- ✅ Compressed OOPs -- ✅ Transparent huge pages -- ✅ Optimized string concatenation -- ✅ Better random number generation - -**File**: `scripts/start.sh` (already updated) - -### 3. Docker Optimizations - -- ✅ Platform specification (`platform: linux/arm64`) -- ✅ Resource limits configured -- ✅ Image cleanup in Dockerfile - -**Files**: `docker-compose.yml`, `Dockerfile` (already updated) - -### 4. Storage Optimizations - -- ✅ TRIM enabled -- ✅ Log rotation configured -- ✅ Journal logging optimized -- ✅ USB power management - -**Script**: `scripts/optimize-rpi5.sh` - -### 5. Network Optimizations - -- ✅ TCP congestion control (BBR) -- ✅ Increased buffer sizes -- ✅ Optimized connection limits - -**Script**: `scripts/optimize-rpi5.sh` - -## 📊 Performance Monitoring - -### Enhanced Monitor Script - -`scripts/monitor-rpi5.sh` provides: - -- CPU temperature and frequency -- Memory usage -- Disk usage -- Docker container stats -- Network statistics -- Performance warnings - -### Usage - -```bash -./scripts/monitor-rpi5.sh -``` - -## 🎯 Expected Performance Improvements - -### Before Optimization - -- CPU: Variable frequency -- Memory: Higher swap usage -- Network: Default TCP settings -- Storage: No TRIM, more writes - -### After Optimization - -- CPU: Maximum frequency (performance mode) -- Memory: Reduced swap usage -- Network: BBR congestion control, larger buffers -- Storage: TRIM enabled, reduced writes -- JVM: Better memory management - -### Performance Targets - -- **TPS**: 20 TPS (constant) -- **CPU Usage**: <80% average -- **Memory**: <90% of allocated -- **Temperature**: <70°C under load -- **Network Latency**: <50ms local - -## 🔧 Manual Optimizations - -### CPU Governor (Manual) - -```bash -sudo apt install cpufrequtils -echo 'GOVERNOR="performance"' | sudo tee /etc/default/cpufrequtils -sudo systemctl enable cpufrequtils -sudo systemctl start cpufrequtils -``` - -### Swap Optimization (Manual) - -```bash -# For 4GB Pi -sudo dphys-swapfile swapoff -sudo sed -i 's/CONF_SWAPSIZE=100/CONF_SWAPSIZE=512/' /etc/dphys-swapfile -sudo dphys-swapfile setup -sudo dphys-swapfile swapon -``` - -### Kernel Parameters (Manual) - -```bash -sudo nano /etc/sysctl.conf -# Add optimizations from RASPBERRY_PI_OPTIMIZATIONS.md -sudo sysctl -p -``` - -## 📈 Monitoring & Benchmarking - -### Before/After Comparison - -```bash -# Before -./scripts/monitor-rpi5.sh > benchmark-before.txt - -# Apply optimizations -./scripts/optimize-rpi5.sh - -# After -./scripts/monitor-rpi5.sh > benchmark-after.txt - -# Compare -diff benchmark-before.txt benchmark-after.txt -``` - -## ⚠️ Important Notes - -1. **Reboot Required**: Some optimizations require a reboot -2. **Temperature**: Monitor CPU temperature after optimizations -3. **Testing**: Test server performance after applying optimizations -4. **Backup**: Backup configuration before making changes - -## 📚 Full Documentation - -For detailed information, see: - -- **[RASPBERRY_PI_OPTIMIZATIONS.md](RASPBERRY_PI_OPTIMIZATIONS.md)** - Complete optimization guide -- **[RASPBERRY_PI_COMPATIBILITY.md](RASPBERRY_PI_COMPATIBILITY.md)** - Compatibility guide -- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Performance troubleshooting - -## 🎮 Gameplay Optimizations - -### Server Properties - -For best performance on Pi 5: - -```properties -view-distance=10 -simulation-distance=8 -max-players=8 -network-compression-threshold=256 -max-tick-time=60000 -``` - -### Memory Settings - -**4GB Pi**: - -```yaml -MEMORY_MIN=1G -MEMORY_MAX=2G -``` - -**8GB Pi**: - -```yaml -MEMORY_MIN=2G -MEMORY_MAX=4G -``` - -## 🔄 Maintenance - -### Regular Tasks - -1. **Monitor Performance**: Run `monitor-rpi5.sh` weekly -2. **Check Logs**: Review server logs for issues -3. **Update System**: Keep Raspberry Pi OS updated -4. **Clean Backups**: Remove old backups periodically - -### Performance Checks - -```bash -# Check temperature -vcgencmd measure_temp - -# Check throttling -vcgencmd get_throttled - -# Check memory -free -h - -# Check disk -df -h -``` - -## 🚨 Troubleshooting - -### High Temperature - -- Check cooling solution -- Reduce CPU-intensive operations -- Lower view distance - -### High Memory Usage - -- Reduce MEMORY_MAX -- Lower view distance -- Restart server periodically - -### Performance Issues - -- Run optimization script -- Check for throttling -- Monitor resource usage -- Review server.properties - ---- - -**Last Updated**: 2025-01-27 -**Status**: Ready for use diff --git a/docs/archive/SUMMARY.md b/docs/archive/SUMMARY.md deleted file mode 100644 index 03ff922..0000000 --- a/docs/archive/SUMMARY.md +++ /dev/null @@ -1,371 +0,0 @@ -# Project Analysis & Enhancement Summary - -> **Note**: This document is a historical record of project analysis. For current project status, see [CHANGELOG.md](../CHANGELOG.md) and [ROADMAP.md](ROADMAP.md). - -## Executive Summary - -This document summarizes the comprehensive analysis and enhancements made to the Minecraft Server for Raspberry Pi 5 project. The analysis included reviewing all documentation, configuration files, and current project state to create an extensive roadmap, detailed task breakdown, and workspace optimizations. - ---- - -## Analysis Performed - -### 1. Documentation Review -- ✅ README.md - Main project documentation -- ✅ CHANGELOG.md - Version history and planned features -- ✅ CONTRIBUTING.md - Contribution guidelines -- ✅ INSTALL.md - Installation instructions -- ✅ CONFIGURATION_EXAMPLES.md - Configuration examples -- ✅ QUICK_REFERENCE.md - Command reference -- ✅ TROUBLESHOOTING.md - Problem solving guide - -### 2. Configuration Review -- ✅ docker-compose.yml - Docker service configuration -- ✅ Dockerfile - Container image definition -- ✅ manage.sh - Server management script -- ✅ start.sh - Server startup script -- ✅ setup-rpi.sh - Raspberry Pi setup script -- ✅ server.properties - Server configuration -- ✅ .gitignore - Git exclusions - -### 3. Current State Assessment -- ✅ Identified implemented features -- ✅ Documented known limitations -- ✅ Reviewed planned features from CHANGELOG -- ✅ Analyzed project structure -- ✅ Assessed technical debt - ---- - -## Deliverables Created - -### 1. ROADMAP.md - Comprehensive Development Roadmap - -**Contents:** -- Current state analysis (v1.0.0) -- Phase 1: Core Enhancements (v1.1.0 - v1.3.0) - - Automation & Monitoring - - Server Variants & Plugins - - Multi-World & Advanced Features -- Phase 2: Web Interface & Integration (v1.4.0 - v1.6.0) - - Web Admin Panel - - Dynamic DNS & Networking - - Cloud Integration -- Phase 3: Advanced Features & Enterprise (v2.0.0+) - - Multi-Server Orchestration - - Analytics & Intelligence - - Enterprise Features -- Phase 4: Community & Ecosystem (v2.3.0+) - - Community Features - - Developer Tools -- Infrastructure & Technical Debt -- Research & Experimental Features -- Priority Matrix -- Success Metrics -- Timeline Summary (Q1 2025 - Q3 2027) - -**Key Features:** -- 70+ planned features organized by priority -- Detailed timeline spanning 2+ years -- Clear priority classification (P0-P3) -- Success metrics and KPIs - -### 2. TASKS.md - Detailed Task Breakdown - -**Contents:** -- 70+ detailed tasks organized by feature -- Priority classification (P0-P3) -- Task status tracking -- Task assignment guidelines -- Completion status summary - -**Task Categories:** -- Backup & Scheduling (6 tasks) -- Monitoring & Metrics (8 tasks) -- Update Management (3 tasks) -- Server Variants (5 tasks) -- Plugin Management (4 tasks) -- Multi-World Support (3 tasks) -- Web Interface (6 tasks) -- Authentication & Security (3 tasks) -- Dynamic DNS (3 tasks) -- Cloud Backup (2 tasks) -- Infrastructure (10 tasks) - -**Task Details Include:** -- Task ID and description -- Implementation steps -- Testing requirements -- Documentation updates needed -- Dependencies - -### 3. Workspace Optimizations - -#### Configuration Files Created - -**Makefile** -- 15+ convenient commands -- Server management shortcuts -- Development commands -- Testing and build commands - -**.editorconfig** -- Consistent code formatting -- File-type specific settings -- Cross-editor compatibility - -**.pre-commit-config.yaml** -- Automated code quality checks -- Shell script linting -- YAML/JSON validation -- Markdown linting - -**.vscode/settings.json** -- Editor configuration -- File associations -- Exclude patterns -- Spell checker configuration - -**.vscode/extensions.json** -- Recommended extensions -- Docker support -- Shell script support -- YAML support - -**.vscode/launch.json** -- Debug configurations -- Shell script debugging - -**.github/workflows/ci.yml** -- Automated CI pipeline -- Syntax checking -- Docker Compose validation -- Runs on push and PR - -#### Enhanced Files - -**docker-compose.yml** -- Environment variable support -- Healthcheck configuration -- Logging with rotation -- Resource limits -- Custom network configuration -- Improved flexibility - -**.gitignore** -- Better organization -- Environment file exclusion -- Config file exclusions -- Future-proofing for web panel - -#### Documentation Created - -**DEVELOPMENT.md** -- Development environment setup -- Development workflow -- Code standards -- Project structure -- Common tasks -- Debugging guide -- Release process - -**WORKSPACE_ENHANCEMENTS.md** -- Summary of all enhancements -- New features available -- Migration notes -- Benefits for different user types - -**config/README.md** -- Configuration directory structure -- File descriptions -- Usage instructions - -**scripts/README.md** -- Scripts directory documentation -- Best practices -- Adding new scripts guide - ---- - -## Key Improvements - -### 1. Project Organization -- ✅ Clear directory structure -- ✅ Comprehensive documentation -- ✅ Consistent code formatting -- ✅ Automated quality checks - -### 2. Developer Experience -- ✅ VS Code integration -- ✅ Pre-commit hooks -- ✅ Makefile for convenience -- ✅ CI/CD pipeline -- ✅ Development guide - -### 3. Configuration Management -- ✅ Environment variable support -- ✅ .env file template -- ✅ Flexible docker-compose.yml -- ✅ Configuration directory structure - -### 4. Future Planning -- ✅ Comprehensive roadmap -- ✅ Detailed task breakdown -- ✅ Priority classification -- ✅ Timeline estimates -- ✅ Success metrics - -### 5. Code Quality -- ✅ Automated linting -- ✅ Syntax checking -- ✅ Pre-commit hooks -- ✅ CI/CD validation - ---- - -## Roadmap Highlights - -### Phase 1 (v1.1.0 - v1.3.0) - Q1-Q3 2025 -**Focus: Core Enhancements** -- Automated backup scheduling -- Performance monitoring dashboard -- Automatic updates -- Paper/Spigot server support -- Plugin management -- Multi-world support - -### Phase 2 (v1.4.0 - v1.6.0) - Q4 2025 - Q2 2026 -**Focus: Web Interface & Integration** -- Web-based admin panel -- Dynamic DNS integration -- Cloud backup integration -- Mobile app - -### Phase 3 (v2.0.0+) - Q3 2026+ -**Focus: Advanced Features** -- Multi-server orchestration -- Analytics & intelligence -- Enterprise features -- Community features - ---- - -## Task Statistics - -### By Priority -- **P0 (Critical)**: 15 tasks -- **P1 (High)**: 25 tasks -- **P2 (Medium)**: 20 tasks -- **P3 (Low)**: 10 tasks - -### By Phase -- **Phase 1**: 40 tasks -- **Phase 2**: 15 tasks -- **Infrastructure**: 10 tasks -- **Total**: 70 tasks - -### Completion Status -- **Completed**: 0 (baseline established) -- **In Progress**: 0 -- **Pending**: 70 - ---- - -## Next Steps - -### Immediate Actions -1. ✅ Review ROADMAP.md for project direction -2. ✅ Review TASKS.md for specific work items -3. ✅ Set up development environment (see DEVELOPMENT.md) -4. ✅ Create .env file from template -5. ✅ Install pre-commit hooks (optional) -6. ✅ Test workspace enhancements - -### Short-term (Next Sprint) -1. Start with P0 tasks from TASKS.md -2. Implement automated backup scheduling -3. Add performance monitoring -4. Set up CI/CD pipeline testing - -### Long-term -1. Follow roadmap phases -2. Regular roadmap reviews (quarterly) -3. Update tasks as features are completed -4. Gather community feedback - ---- - -## Benefits Summary - -### For Users -- ✅ Better documentation -- ✅ Clearer project direction -- ✅ More reliable updates -- ✅ Easier configuration - -### For Developers -- ✅ Comprehensive roadmap -- ✅ Detailed task breakdown -- ✅ Better development environment -- ✅ Clear contribution guidelines - -### For Maintainers -- ✅ Organized project structure -- ✅ Automated quality checks -- ✅ Clear priorities -- ✅ Easier maintenance - ---- - -## Files Created/Modified - -### New Files (15) -1. ROADMAP.md -2. TASKS.md -3. DEVELOPMENT.md -4. WORKSPACE_ENHANCEMENTS.md -5. SUMMARY.md (this file) -6. Makefile -7. .editorconfig -8. .pre-commit-config.yaml -9. .vscode/settings.json -10. .vscode/extensions.json -11. .vscode/launch.json -12. .github/workflows/ci.yml -13. config/README.md -14. scripts/README.md -15. .env.example (template - create manually) - -### Modified Files (3) -1. docker-compose.yml (enhanced) -2. .gitignore (improved) -3. README.md (updated with new docs) - ---- - -## Conclusion - -This comprehensive analysis and enhancement effort has: - -1. **Created a clear roadmap** spanning 2+ years with 70+ features -2. **Organized tasks** into actionable items with priorities -3. **Optimized the workspace** for better development experience -4. **Enhanced configuration** for flexibility and maintainability -5. **Improved documentation** for all user types - -The project now has: -- Clear direction and priorities -- Detailed implementation plans -- Better development tools -- Comprehensive documentation -- Automated quality checks - -All enhancements are backward compatible and can be adopted gradually. - ---- - -**Analysis Date**: 2025-01-XX -**Analyst**: AI Assistant -**Project Version**: 1.0.0 -**Next Review**: Quarterly - diff --git a/docs/archive/TESTING_COMPLETE.md b/docs/archive/TESTING_COMPLETE.md deleted file mode 100644 index 09b4da2..0000000 --- a/docs/archive/TESTING_COMPLETE.md +++ /dev/null @@ -1,403 +0,0 @@ -# Complete Testing Guide - -This document provides a comprehensive overview of all testing capabilities in the Minecraft Server Management project. - -## Test Coverage Summary - -### Current Coverage Status - -| Test Type | Coverage | Target | Status | -| -------------------- | -------- | ------- | ------------- | -| API Tests | ~65% | 70% | ✅ Good | -| Component Tests | ~60% | 70% | ✅ Good | -| Integration Tests | ~50% | 60% | ✅ Good | -| E2E Tests | ~45% | 50% | ✅ Good | -| Unit Tests (Scripts) | ~50% | 60% | ⚠️ Needs work | -| **Overall** | **~60%** | **70%** | ✅ **Good** | - -## Test Types - -### 1. Unit Tests - -#### Python Unit Tests - -- **Location**: `tests/api/` -- **Framework**: pytest -- **Coverage**: API endpoints, analytics processor algorithms - -**Files**: - -- `test_api.py` - Basic API tests -- `test_analytics.py` - Analytics endpoint tests -- `test_api_comprehensive.py` - Comprehensive API tests -- `test_analytics_processor.py` - Analytics algorithm tests -- `test_auth.py` - Authentication tests -- `test_rbac.py` - RBAC tests -- `test_backup_management.py` - Backup tests -- `test_config_files.py` - Config file tests - -#### Bash Script Unit Tests - -- **Location**: `tests/unit/` -- **Framework**: BATS -- **Coverage**: Management scripts - -**Files**: - -- `test-manage.sh` - Server management script tests -- `test-backup-scheduler.sh` - Backup scheduler tests -- `test-log-manager.sh` - Log manager tests -- `test-analytics-collector.sh` - Analytics collector tests - -### 2. Component Tests - -#### React Component Tests - -- **Location**: `web/src/pages/__tests__/` and `web/src/components/__tests__/` -- **Framework**: Vitest + React Testing Library -- **Coverage**: UI components - -**Files**: - -- `Analytics.test.jsx` - Analytics component (15+ tests) -- `Dashboard.test.jsx` - Dashboard component -- `Backups.test.jsx` - Backups component (NEW) -- `Players.test.jsx` - Players component (NEW) -- `Worlds.test.jsx` - Worlds component (NEW) -- `Login.test.jsx` - Login component -- `Register.test.jsx` - Registration component -- And more... - -### 3. Integration Tests - -#### API Integration Tests - -- **Location**: `tests/integration/` -- **Framework**: BATS -- **Coverage**: System integration - -**Files**: - -- `test-backup-system.sh` - Backup system integration -- `test-monitoring.sh` - Monitoring integration -- `test-plugin-management.sh` - Plugin management -- `test-rcon.sh` - RCON integration -- `test-world-management.sh` - World management -- `test-analytics.sh` - Analytics system integration (NEW) - -#### React Integration Tests - -- **Location**: `web/src/test/integration/` -- **Framework**: Vitest -- **Coverage**: Component workflows - -**Files**: - -- `analytics.integration.test.jsx` - Analytics workflow (NEW) -- `dashboard.integration.test.jsx` - Dashboard workflow -- `logs.integration.test.jsx` - Logs workflow - -### 4. End-to-End Tests - -#### API E2E Tests - -- **Location**: `tests/e2e/` -- **Framework**: BATS -- **Coverage**: Complete workflows - -**Files**: - -- `test-api-workflow.sh` - API workflow -- `test-backup-workflow.sh` - Backup workflow -- `test-server-lifecycle.sh` - Server lifecycle -- `test-analytics-workflow.sh` - Analytics workflow (NEW) -- `test-complete-user-journey.sh` - Complete user journey (NEW) -- `test-web-ui-workflow.sh` - Web UI workflow (NEW) - -#### Browser E2E Tests - -- **Location**: `tests/e2e/browser/` -- **Framework**: Playwright -- **Coverage**: Real browser testing - -**Files**: - -- `analytics.spec.js` - Analytics page browser tests (NEW) -- `user-journey.spec.js` - User journey browser tests (NEW) -- `visual-regression.spec.js` - Visual regression tests (NEW) - -### 5. Accessibility Tests - -#### A11y Tests - -- **Location**: `web/src/test/a11y.test.jsx` -- **Framework**: jest-axe -- **Coverage**: WCAG compliance - -**Tests**: - -- Analytics page accessibility -- Dashboard accessibility -- Backups page accessibility -- Players page accessibility -- Worlds page accessibility -- Login page accessibility -- Form label validation - -### 6. Visual Regression Tests - -#### Visual Tests - -- **Location**: `tests/e2e/browser/visual-regression.spec.js` -- **Framework**: Playwright -- **Coverage**: UI visual consistency - -**Tests**: - -- Dashboard visual snapshot -- Analytics page visual snapshot -- Backups page visual snapshot -- Players page visual snapshot -- Worlds page visual snapshot -- Login page visual snapshot - -## Running Tests - -### All Tests - -```bash -# Run all test suites -./scripts/run-tests.sh -``` - -### Python Tests - -```bash -# All Python tests -pytest tests/api/ -v - -# With coverage -pytest tests/api/ --cov=api --cov-report=html - -# Specific test file -pytest tests/api/test_analytics.py -v -``` - -### Component Tests - -```bash -cd web -npm test # All tests -npm test Analytics # Analytics tests -npm test Backups # Backups tests -npm test Players # Players tests -npm test Worlds # Worlds tests -npm run test:coverage # With coverage -``` - -### Integration Tests - -```bash -# Bash integration tests -bats tests/integration/test-analytics.sh - -# React integration tests -cd web -npm test integration -``` - -### E2E Tests - -```bash -# API E2E tests -bats tests/e2e/test-complete-user-journey.sh -bats tests/e2e/test-web-ui-workflow.sh - -# Browser E2E tests -cd web -npx playwright test - -# Visual regression -npx playwright test tests/e2e/browser/visual-regression.spec.js -``` - -### Accessibility Tests - -```bash -cd web -npm test a11y -``` - -## Test Configuration - -### Vitest Configuration - -- **File**: `web/vitest.config.js` -- **Environment**: jsdom -- **Coverage**: v8 provider -- **Setup**: `web/src/test/setup.js` - -### Playwright Configuration - -- **File**: `playwright.config.js` -- **Browsers**: Chromium, Firefox, WebKit -- **Base URL**: -- **Screenshots**: On failure - -### Pytest Configuration - -- **File**: `tests/api/pytest.ini` -- **Markers**: unit, integration, api, slow -- **Coverage**: pytest-cov - -## Test Best Practices - -### Writing Tests - -1. **Follow AAA Pattern** - - ```javascript - // Arrange - const mockData = {...}; - - // Act - render(); - - // Assert - expect(screen.getByText('Expected')).toBeInTheDocument(); - ``` - -2. **Test User Behavior** - - - Test what users see and do - - Avoid testing implementation details - - Use semantic queries - -3. **Mock External Dependencies** - - ```javascript - vi.mock('../services/api'); - ``` - -4. **Clean Up** - - ```javascript - afterEach(() => { - vi.clearAllMocks(); - }); - ``` - -### Test Organization - -``` -tests/ -├── api/ # Python API tests -├── unit/ # Bash script tests -├── integration/ # Integration tests -├── e2e/ # E2E tests -│ └── browser/ # Browser automation -└── helpers/ # Test utilities - -web/src/ -├── pages/__tests__/ # Component tests -├── components/__tests__/ # Component tests -└── test/ # Test utilities & integration - ├── integration/ # Integration tests - ├── mocks/ # Mock handlers - └── a11y.test.jsx # Accessibility tests -``` - -## Coverage Goals - -### Current Status - -- **Overall**: ~60% coverage -- **API**: ~65% coverage -- **Components**: ~60% coverage -- **E2E**: ~45% coverage - -### Target Goals - -- **Overall**: 70%+ coverage -- **API**: 75%+ coverage -- **Components**: 70%+ coverage -- **E2E**: 50%+ coverage - -## CI/CD Integration - -### GitHub Actions - -- Runs on pull requests -- Runs on pushes to main -- Generates coverage reports -- Publishes test results - -### Test Workflows - -- `.github/workflows/tests.yml` - Main test workflow -- `.github/workflows/coverage.yml` - Coverage reporting - -## New Test Files Added - -### Analytics Tests - -1. ✅ `tests/api/test_analytics.py` - API endpoint tests -2. ✅ `tests/api/test_analytics_processor.py` - Algorithm tests (NEW) -3. ✅ `web/src/pages/__tests__/Analytics.test.jsx` - Component tests -4. ✅ `web/src/test/integration/analytics.integration.test.jsx` - Integration tests -5. ✅ `tests/integration/test-analytics.sh` - System integration -6. ✅ `tests/e2e/test-analytics-workflow.sh` - E2E workflow - -### Component Tests - -7. ✅ `web/src/pages/__tests__/Backups.test.jsx` - Backups component (NEW) -8. ✅ `web/src/pages/__tests__/Players.test.jsx` - Players component (NEW) -9. ✅ `web/src/pages/__tests__/Worlds.test.jsx` - Worlds component (NEW) - -### E2E Tests - -10. ✅ `tests/e2e/test-complete-user-journey.sh` - Complete journey -11. ✅ `tests/e2e/test-web-ui-workflow.sh` - Web UI workflow -12. ✅ `tests/e2e/browser/analytics.spec.js` - Browser tests (NEW) -13. ✅ `tests/e2e/browser/user-journey.spec.js` - Browser journey (NEW) - -### Accessibility & Visual - -14. ✅ `web/src/test/a11y.test.jsx` - Accessibility tests (NEW) -15. ✅ `tests/e2e/browser/visual-regression.spec.js` - Visual tests (NEW) - -## Test Statistics - -- **Total Test Files**: 30+ -- **Total Test Cases**: 200+ -- **Component Tests**: 50+ -- **API Tests**: 80+ -- **E2E Tests**: 40+ -- **Integration Tests**: 20+ -- **Accessibility Tests**: 6+ -- **Visual Tests**: 6+ - -## Next Steps - -### Completed ✅ - -1. ✅ Analytics processor unit tests -2. ✅ Component tests for Backups, Players, Worlds -3. ✅ Visual regression tests -4. ✅ Accessibility tests -5. ✅ Browser automation with Playwright - -### Future Enhancements - -1. Performance tests -2. Load tests -3. Security tests -4. Cross-browser compatibility tests -5. Mobile responsive tests - -## See Also - -- [Testing Guide](TESTING.md) -- [Web UI Testing Guide](WEB_UI_TESTING.md) -- [Test Coverage Guide](TEST_COVERAGE.md) -- [Analytics Tests](ANALYTICS_TESTS.md) diff --git a/docs/archive/TESTING_ENHANCEMENTS.md b/docs/archive/TESTING_ENHANCEMENTS.md deleted file mode 100644 index 437c323..0000000 --- a/docs/archive/TESTING_ENHANCEMENTS.md +++ /dev/null @@ -1,372 +0,0 @@ -# Testing Framework Enhancements - -This document describes the comprehensive enhancements made to the testing framework. - -## Overview - -The testing framework has been significantly enhanced with new utilities, tools, and capabilities to improve test quality, coverage, and developer experience. - -## New Features - -### 1. Test Data Factories - -**Location**: `tests/api/factories.py` - -Reusable factories for creating test data: - -- `generate_api_key()` - Generate random API keys -- `create_user_data()` - Create test user data -- `create_api_key_data()` - Create test API key data -- `create_backup_metadata()` - Create backup metadata -- `create_server_properties()` - Generate server.properties content -- `create_whitelist_entry()` - Create whitelist entries -- `create_ban_entry()` - Create ban entries -- `create_world_data()` - Create world data -- `create_plugin_data()` - Create plugin data - -**Usage**: - -```python -from tests.api.factories import create_user_data, create_api_key_data - -user = create_user_data(username="testuser", role="admin") -api_key = create_api_key_data(name="test-key") -``` - -### 2. Enhanced Test Fixtures - -**Location**: `tests/api/conftest.py` - -New fixtures added: - -- `test_user_data` - Factory-generated user data -- `test_api_key_data` - Factory-generated API key data -- `test_backup_metadata` - Factory-generated backup metadata -- `test_server_properties` - Server.properties content -- `test_data_dir` - Temporary data directory with subdirectories -- `test_backup_dir` - Temporary backup directory -- `mock_docker` - Mock Docker operations -- `mock_file_system` - Mock file system operations -- `mock_network` - Mock network operations -- `isolated_test_env` - Isolated test environment with directories - -**Usage**: - -```python -def test_something(test_user_data, test_data_dir, mock_docker): - # Use fixtures in tests - user = test_user_data - data_path = test_data_dir / "world" -``` - -### 3. Test Parallelization - -**Configuration**: `tests/api/pytest.ini` - -Tests can now run in parallel using `pytest-xdist`: - -```bash -# Run tests in parallel (auto-detects CPU count) -pytest -n auto - -# Or specify number of workers -pytest -n 4 -``` - -**Makefile command**: - -```bash -make test-api-parallel -``` - -### 4. Enhanced Test Reporting - -**Configuration**: `tests/api/pytest.ini` - -Multiple report formats now available: - -- **Terminal**: `--cov-report=term-missing` (default) -- **HTML**: `--cov-report=html:htmlcov` -- **JSON**: `--cov-report=json:coverage.json` -- **XML**: `--cov-report=xml:coverage.xml` (for CI/CD) -- **JUnit**: Built-in JUnit XML support - -Reports are automatically generated when running tests with coverage. - -### 5. Performance Testing Utilities - -**Location**: `tests/api/performance_utils.py` - -Utilities for performance and load testing: - -- `PerformanceTimer` - Context manager for timing operations -- `measure_execution_time()` - Measure function execution time -- `run_load_test()` - Run load tests with threading -- `print_performance_report()` - Format and print performance results -- `benchmark_endpoint()` - Benchmark API endpoints - -**Usage**: - -```python -from tests.api.performance_utils import PerformanceTimer, run_load_test - -# Time a single operation -with PerformanceTimer("Operation") as timer: - do_something() -print(f"Duration: {timer.get_duration()}s") - -# Load test -results = run_load_test(my_function, num_requests=100, num_threads=10) -print_performance_report(results) -``` - -**Example Test**: - -```python -@pytest.mark.performance -def test_endpoint_performance(client): - results = benchmark_endpoint( - client, 'GET', '/api/health', - num_requests=100, num_threads=10 - ) - assert results['avg_duration'] < 0.1 -``` - -### 6. API Contract Testing - -**Location**: `tests/api/contract_test_utils.py` - -Utilities for validating API contracts against OpenAPI schema: - -- `load_openapi_schema()` - Load OpenAPI schema from file -- `validate_response_schema()` - Validate API response against schema -- `validate_request_schema()` - Validate API request against schema -- `get_endpoint_schema()` - Get schema definition for endpoint - -**Usage**: - -```python -from tests.api.contract_test_utils import validate_response_schema - -response = client.get('/api/health') -data = json.loads(response.data) -is_valid, error = validate_response_schema(data, '/api/health', 'GET', 200) -assert is_valid -``` - -**Example Test**: - -```python -@pytest.mark.contract -def test_endpoint_contract(client): - response = client.get('/api/health') - data = json.loads(response.data) - is_valid, error = validate_response_schema(data, '/api/health', 'GET', 200) - assert is_valid, error -``` - -### 7. Coverage Gap Analysis - -**Location**: `scripts/analyze-coverage-gaps.sh` - -Tool to identify untested code paths and suggest improvements: - -```bash -# Analyze coverage gaps -./scripts/analyze-coverage-gaps.sh analyze - -# Show detailed gaps -./scripts/analyze-coverage-gaps.sh detailed - -# Get improvement suggestions -./scripts/analyze-coverage-gaps.sh suggest -``` - -**Makefile commands**: - -```bash -make coverage-gaps -make coverage-gaps-detailed -make coverage-suggestions -``` - -The tool: - -- Identifies files with coverage < 80% -- Shows missing line numbers -- Suggests test improvements -- Generates detailed reports - -### 8. Enhanced Test Isolation - -**Location**: `tests/api/conftest.py` - -Improved test isolation with: - -- Automatic cleanup via `tmp_path` fixture -- Isolated test environments with `isolated_test_env` fixture -- Mock fixtures that don't interfere with each other -- Better teardown between tests - -## New Test Files - -### Performance Tests - -**Location**: `tests/api/test_performance.py` - -Performance tests for API endpoints: - -- Health endpoint performance -- Load testing -- Response time validation -- Throughput measurement - -Run with: - -```bash -pytest -m performance -# or -make test-api-performance -``` - -### Contract Tests - -**Location**: `tests/api/test_contract.py` - -API contract validation tests: - -- Response schema validation -- Request schema validation -- OpenAPI compliance - -Run with: - -```bash -pytest -m contract -# or -make test-api-contract -``` - -### Factory Tests - -**Location**: `tests/api/test_factories.py` - -Tests for test data factories to ensure they work correctly. - -## Updated Configuration - -### pytest.ini - -Enhanced with: - -- Multiple coverage report formats -- New test markers (performance, contract, e2e) -- Better error reporting - -### Makefile - -New commands: - -- `make test-api-parallel` - Run tests in parallel -- `make test-api-performance` - Run performance tests -- `make test-api-contract` - Run contract tests -- `make test-factories` - Test factory utilities -- `make coverage-gaps` - Analyze coverage gaps -- `make coverage-gaps-detailed` - Detailed gap analysis -- `make coverage-suggestions` - Get improvement suggestions - -### Test Requirements - -**Location**: `api/requirements-test.txt` - -New testing dependencies: - -- `pytest-xdist` - Parallel test execution -- `pytest-mock` - Enhanced mocking -- `pytest-timeout` - Test timeout support -- `jsonschema` - Schema validation -- `pyyaml` - YAML parsing for OpenAPI - -Install with: - -```bash -pip install -r api/requirements-test.txt -``` - -## Usage Examples - -### Running Tests with New Features - -```bash -# Run all tests with parallel execution -make test-api-parallel - -# Run performance tests -make test-api-performance - -# Run contract tests -make test-api-contract - -# Analyze coverage gaps -make coverage-gaps - -# Generate all coverage reports -make coverage -``` - -### Writing Tests with New Utilities - -```python -import pytest -from tests.api.factories import create_user_data -from tests.api.performance_utils import PerformanceTimer - -@pytest.mark.performance -def test_user_creation_performance(client, test_user_data): - with PerformanceTimer("User creation") as timer: - response = client.post('/api/auth/register', json=test_user_data) - assert response.status_code == 200 - assert timer.get_duration() < 0.5 -``` - -## Benefits - -1. **Faster Test Execution**: Parallel execution reduces test time -2. **Better Coverage Analysis**: Gap analysis identifies untested code -3. **Performance Monitoring**: Built-in performance testing utilities -4. **API Contract Validation**: Ensures API compliance with OpenAPI -5. **Reusable Test Data**: Factories reduce test setup code -6. **Better Reporting**: Multiple report formats for different needs -7. **Improved Isolation**: Better test isolation prevents interference - -## Migration Guide - -### Existing Tests - -No changes required for existing tests. New utilities are optional. - -### New Tests - -Use new utilities for: - -- Creating test data (use factories) -- Performance testing (use performance utilities) -- Contract validation (use contract utilities) -- Load testing (use load test functions) - -## Future Enhancements - -Potential future improvements: - -1. **Mutation Testing**: Add mutation testing for test quality -2. **Visual Regression**: Enhanced visual regression testing -3. **API Fuzzing**: Automated API fuzzing tests -4. **Database Testing**: Database-specific test utilities -5. **Integration Test Helpers**: More integration test utilities - -## Resources - -- [pytest Documentation](https://docs.pytest.org/) -- [pytest-xdist Documentation](https://pytest-xdist.readthedocs.io/) -- [Coverage.py Documentation](https://coverage.readthedocs.io/) -- [JSON Schema Validation](https://python-jsonschema.readthedocs.io/) diff --git a/docs/archive/TESTING_FINAL_SUMMARY.md b/docs/archive/TESTING_FINAL_SUMMARY.md deleted file mode 100644 index c8bd024..0000000 --- a/docs/archive/TESTING_FINAL_SUMMARY.md +++ /dev/null @@ -1,243 +0,0 @@ -# Final Testing Implementation Summary - -## ✅ All Optional Next Steps Completed - -All requested test improvements have been successfully implemented! - -## What Was Added - -### 1. Analytics Processor Unit Tests ✅ - -**File**: `tests/api/test_analytics_processor.py` - -**30+ comprehensive unit tests** covering: -- ✅ Data loading (empty files, filtering, invalid JSON) -- ✅ Trend calculation (increasing, decreasing, stable) -- ✅ Anomaly detection (Z-score algorithm, severity) -- ✅ Predictions (linear prediction, confidence) -- ✅ Player behavior (unique players, peak hours) -- ✅ Report generation (structure, warnings, recommendations) -- ✅ Performance trends analysis - -### 2. Component Tests for Backups, Players, Worlds ✅ - -**Files**: -- `web/src/pages/__tests__/Backups.test.jsx` - **12+ tests** -- `web/src/pages/__tests__/Players.test.jsx` - **8+ tests** -- `web/src/pages/__tests__/Worlds.test.jsx` - **6+ tests** - -**Coverage**: -- Component rendering -- Loading and empty states -- User interactions -- Error handling -- API integration - -### 3. Visual Regression Tests ✅ - -**File**: `tests/e2e/browser/visual-regression.spec.js` - -**6 visual snapshot tests**: -- Dashboard -- Analytics -- Backups -- Players -- Worlds -- Login - -**Framework**: Playwright with screenshot comparison - -### 4. Accessibility Tests ✅ - -**File**: `web/src/test/a11y.test.jsx` - -**7 accessibility tests** using jest-axe: -- Analytics page (WCAG compliance) -- Dashboard page -- Backups page -- Players page -- Worlds page -- Login page -- Form label validation - -### 5. Browser Automation with Playwright ✅ - -**Files**: -- `playwright.config.js` - Configuration -- `tests/e2e/browser/analytics.spec.js` - Analytics browser tests -- `tests/e2e/browser/user-journey.spec.js` - User journey tests -- `tests/e2e/browser/visual-regression.spec.js` - Visual tests -- `.github/workflows/playwright.yml` - CI/CD integration - -**Features**: -- Real browser testing (Chromium, Firefox, WebKit) -- Complete user workflows -- Visual regression -- Cross-browser compatibility - -## Final Coverage Statistics - -### Overall Coverage -- **Before**: ~51% -- **After**: **~70%+** ✅ -- **Improvement**: +19% - -### By Area -| Area | Before | After | Improvement | -|------|--------|-------|-------------| -| API Tests | ~40% | ~75% | +35% | -| Component Tests | ~20% | ~70% | +50% | -| E2E Tests | ~15% | ~55% | +40% | -| Analytics | 0% | ~95% | +95% | -| Unit Tests (Scripts) | ~40% | ~50% | +10% | - -### Test Count -- **Total Test Files**: 30+ -- **Total Test Cases**: 250+ -- **New Test Cases Added**: 100+ - -## New Test Files Summary - -### Analytics Tests (8 files) -1. ✅ `tests/api/test_analytics.py` -2. ✅ `tests/api/test_analytics_processor.py` -3. ✅ `web/src/pages/__tests__/Analytics.test.jsx` -4. ✅ `web/src/test/integration/analytics.integration.test.jsx` -5. ✅ `tests/integration/test-analytics.sh` -6. ✅ `tests/e2e/test-analytics-workflow.sh` -7. ✅ `tests/unit/test-analytics-collector.sh` -8. ✅ `tests/e2e/browser/analytics.spec.js` - -### Component Tests (3 files) -9. ✅ `web/src/pages/__tests__/Backups.test.jsx` -10. ✅ `web/src/pages/__tests__/Players.test.jsx` -11. ✅ `web/src/pages/__tests__/Worlds.test.jsx` - -### E2E Tests (5 files) -12. ✅ `tests/e2e/test-complete-user-journey.sh` -13. ✅ `tests/e2e/test-web-ui-workflow.sh` -14. ✅ `tests/e2e/browser/user-journey.spec.js` -15. ✅ `tests/e2e/browser/visual-regression.spec.js` -16. ✅ `tests/api/test_api_comprehensive.py` - -### Accessibility & Visual (2 files) -17. ✅ `web/src/test/a11y.test.jsx` -18. ✅ `tests/e2e/browser/visual-regression.spec.js` - -## Running Tests - -### Quick Commands -```bash -# All tests -make test - -# Specific suites -make test-api # Python API tests -make test-web # React component tests -make test-web-a11y # Accessibility tests -make test-playwright # Browser automation -make test-e2e # End-to-end tests -``` - -### Detailed Commands -```bash -# Python tests -pytest tests/api/ -v -pytest tests/api/test_analytics_processor.py -v - -# Component tests -cd web && npm test -cd web && npm test Backups -cd web && npm test Players -cd web && npm test Worlds - -# Accessibility -cd web && npm run test:a11y - -# Browser tests -cd web && npm run test:playwright -cd web && npx playwright test --ui - -# Visual regression -cd web && npx playwright test tests/e2e/browser/visual-regression.spec.js -``` - -## Test Quality - -### ✅ Coverage Goals Met -- Overall: 70%+ ✅ (target: 70%) -- API: 75%+ ✅ (target: 75%) -- Components: 70%+ ✅ (target: 70%) -- E2E: 55%+ ✅ (target: 50%) -- Analytics: 95%+ ✅ (target: 80%) - -### ✅ Test Reliability -- Flaky tests: 0 -- Failing tests: 0 -- Skipped tests: Only E2E (require running server) - -### ✅ Test Execution Speed -- Unit tests: < 5 seconds -- Component tests: < 10 seconds -- Integration tests: < 15 seconds -- Browser tests: < 60 seconds - -## Documentation - -### New Documentation -1. ✅ `docs/TESTING_COMPLETE.md` - Complete testing guide -2. ✅ `docs/WEB_UI_TESTING.md` - Web UI testing guide -3. ✅ `docs/TEST_COVERAGE.md` - Coverage guide -4. ✅ `tests/COMPLETE_TEST_SUMMARY.md` - Complete summary -5. ✅ `tests/e2e/browser/README.md` - Browser tests guide - -## CI/CD Integration - -### GitHub Actions -- ✅ Main test workflow (`.github/workflows/tests.yml`) -- ✅ Coverage reporting (`.github/workflows/coverage.yml`) -- ✅ Playwright tests (`.github/workflows/playwright.yml`) - NEW - -### Automated Testing -- Runs on all pull requests -- Runs on pushes to main -- Generates coverage reports -- Publishes test results -- Screenshots on failure - -## Key Achievements - -### ✅ Comprehensive Coverage -- All major features tested -- Analytics system fully covered -- Web UI components tested -- E2E workflows validated - -### ✅ Quality Assurance -- WCAG accessibility compliance -- Visual regression prevention -- Cross-browser compatibility -- Error handling validation - -### ✅ Developer Experience -- Easy test execution -- Clear organization -- Comprehensive documentation -- CI/CD integration - -## Summary - -**Status**: ✅ **ALL OPTIONAL NEXT STEPS COMPLETED!** - -- ✅ Analytics processor unit tests -- ✅ Component tests (Backups, Players, Worlds) -- ✅ Visual regression tests -- ✅ Accessibility tests -- ✅ Browser automation (Playwright) - -**Final Coverage**: **~70%+ overall** (exceeds 60% target) - -**Test Cases**: **250+ comprehensive tests** - -**Quality**: Production-ready test suite with comprehensive coverage! - diff --git a/playwright.config.js b/playwright.config.js deleted file mode 100644 index 952c2a2..0000000 --- a/playwright.config.js +++ /dev/null @@ -1,41 +0,0 @@ -import { defineConfig, devices } from '@playwright/test'; - -/** - * Playwright configuration for browser automation tests - * @see https://playwright.dev/docs/test-configuration - */ -export default defineConfig({ - testDir: './tests/e2e/browser', - fullyParallel: true, - forbidOnly: !!process.env.CI, - retries: process.env.CI ? 2 : 0, - workers: process.env.CI ? 1 : undefined, - reporter: 'html', - use: { - baseURL: process.env.WEB_URL || 'http://localhost:5173', - trace: 'on-first-retry', - screenshot: 'only-on-failure', - }, - - projects: [ - { - name: 'chromium', - use: { ...devices['Desktop Chrome'] }, - }, - { - name: 'firefox', - use: { ...devices['Desktop Firefox'] }, - }, - { - name: 'webkit', - use: { ...devices['Desktop Safari'] }, - }, - ], - - webServer: { - command: 'npm run dev', - url: 'http://localhost:5173', - reuseExistingServer: !process.env.CI, - timeout: 120 * 1000, - }, -}); diff --git a/pyproject.toml b/pyproject.toml index dc8e7b1..58760cb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,31 +30,20 @@ addopts = [ "--strict-markers", "--tb=short", ] +# Keep in sync with tests/api/pytest.ini, which is the config actually used +# when the suite runs from tests/api (--strict-markers is enabled in both). markers = [ "unit: Unit tests", "integration: Integration tests", "api: API endpoint tests", "slow: Slow running tests", + "performance: Performance tests", + "contract: API contract tests", + "e2e: End-to-end tests", ] -[tool.coverage.run] -source = ["api"] -omit = [ - "*/tests/*", - "*/test_*", - "*/__pycache__/*", -] - -[tool.coverage.report] -exclude_lines = [ - "pragma: no cover", - "def __repr__", - "raise AssertionError", - "raise NotImplementedError", - "if __name__ == .__main__.:", - "if TYPE_CHECKING:", - "@abstractmethod", -] +# Coverage settings live in .coverage-config.ini (a single source of truth, +# referenced explicitly by the Makefile and scripts/check-coverage.sh). [tool.flake8] max-line-length = 120 diff --git a/tests/ANALYTICS_TESTS.md b/tests/ANALYTICS_TESTS.md deleted file mode 100644 index 0eb7766..0000000 --- a/tests/ANALYTICS_TESTS.md +++ /dev/null @@ -1,187 +0,0 @@ -# Analytics Tests Summary - -This document summarizes the new analytics tests added to improve test coverage. - -## New Test Files - -### 1. API Tests: `tests/api/test_analytics.py` - -Comprehensive tests for all analytics API endpoints: - -- **TestAnalyticsCollect**: Tests data collection endpoint - - - Authentication requirements - - Successful collection - - Collection failures - -- **TestAnalyticsReport**: Tests report generation endpoint - - - Report retrieval - - Invalid parameters - - Missing reports - -- **TestAnalyticsTrends**: Tests trends endpoint - - - Performance trends - - Player behavior trends - - Import error handling - -- **TestAnalyticsAnomalies**: Tests anomaly detection - - - Anomaly detection - - No data scenarios - -- **TestAnalyticsPredictions**: Tests predictions endpoint - - - Resource predictions - - Confidence scores - -- **TestPlayerBehavior**: Tests player behavior analytics - - - Behavior analysis - - Peak hours - -- **TestCustomReport**: Tests custom report generation - - Report generation - - Missing fields handling - -**Coverage**: ~95% of analytics endpoints - -### 2. Integration Tests: `tests/integration/test-analytics.sh` - -BATS tests for analytics system integration: - -- Data collection workflow -- Report generation -- Anomaly detection -- Data retention -- End-to-end workflow - -**Coverage**: Complete analytics workflow - -### 3. E2E Tests: `tests/e2e/test-analytics-workflow.sh` - -End-to-end tests via API: - -- Complete API workflow -- Data collection -- Report retrieval -- All analytics endpoints -- Full workflow validation - -**Coverage**: Complete user journey - -### 4. Unit Tests: `tests/unit/test-analytics-collector.sh` - -Unit tests for analytics collector script: - -- Script execution -- File creation -- JSON validation -- Error handling -- Docker failure handling - -**Coverage**: Script functionality - -### 5. Comprehensive API Tests: `tests/api/test_api_comprehensive.py` - -Enhanced tests for existing API endpoints: - -- **TestServerControlComprehensive**: Functional server control tests -- **TestBackupComprehensive**: Backup operation tests -- **TestMetricsComprehensive**: Metrics data retrieval -- **TestConfigFilesComprehensive**: Config file operations -- **TestPlayersComprehensive**: Player management -- **TestWorldsComprehensive**: World management -- **TestErrorHandlingComprehensive**: Error scenarios -- **TestQueryParameters**: Query parameter handling - -**Coverage**: Functional testing beyond auth checks - -## Test Coverage Improvements - -### Before - -- Analytics: 0% coverage -- API endpoints: ~40% (mostly auth checks) -- E2E workflows: ~20% (mostly skipped) - -### After - -- Analytics: ~95% coverage ✅ -- API endpoints: ~65% (functional tests added) -- E2E workflows: ~35% (analytics workflow added) - -## Running the Tests - -### Analytics API Tests - -```bash -pytest tests/api/test_analytics.py -v -``` - -### Comprehensive API Tests - -```bash -pytest tests/api/test_api_comprehensive.py -v -``` - -### Integration Tests - -```bash -bats tests/integration/test-analytics.sh -``` - -### E2E Tests - -```bash -bats tests/e2e/test-analytics-workflow.sh -``` - -### Unit Tests - -```bash -bats tests/unit/test-analytics-collector.sh -``` - -### All Tests - -```bash -./scripts/run-tests.sh -``` - -## Next Steps - -### High Priority - -1. ✅ Analytics API tests - DONE -2. ✅ Analytics integration tests - DONE -3. ✅ Analytics E2E tests - DONE -4. ⚠️ Analytics processor unit tests (Python) - PENDING -5. ⚠️ Web UI component tests - PENDING - -### Medium Priority - -6. Complete E2E workflows for other features -7. More script unit tests -8. Performance tests - -### Low Priority - -9. Load tests -10. Security tests -11. Compatibility tests - -## Test Statistics - -- **New Test Files**: 5 -- **New Test Cases**: ~50+ -- **Coverage Increase**: ~15-20% -- **Analytics Coverage**: 0% → 95% - -## Notes - -- Most E2E tests are marked as `skip` and require running server -- Integration tests require Docker and server setup -- Unit tests can run independently -- API tests use mocks and can run without server diff --git a/tests/COMPLETE_TEST_SUMMARY.md b/tests/COMPLETE_TEST_SUMMARY.md deleted file mode 100644 index 4c5425f..0000000 --- a/tests/COMPLETE_TEST_SUMMARY.md +++ /dev/null @@ -1,325 +0,0 @@ -# Complete Test Implementation Summary - -This document summarizes all tests implemented to improve coverage across the entire project. - -## ✅ All Optional Next Steps Completed - -### 1. Analytics Processor Unit Tests ✅ - -**File**: `tests/api/test_analytics_processor.py` - -**Coverage**: - -- Data loading functionality (empty files, filtering, invalid JSON) -- Trend calculation (increasing, decreasing, stable trends) -- Anomaly detection (Z-score algorithm, severity levels) -- Predictions (linear prediction, confidence scoring) -- Player behavior analysis (unique players, peak hours, hourly distribution) -- Report generation (structure, warnings, recommendations) -- Performance trends analysis - -**Test Cases**: 30+ comprehensive unit tests - -### 2. Component Tests for Backups, Players, Worlds ✅ - -**Files**: - -- `web/src/pages/__tests__/Backups.test.jsx` - 12+ tests -- `web/src/pages/__tests__/Players.test.jsx` - 8+ tests -- `web/src/pages/__tests__/Worlds.test.jsx` - 6+ tests - -**Coverage**: - -- Component rendering -- Loading states -- Data display -- User interactions -- Error handling -- Empty states -- API integration - -### 3. Visual Regression Tests ✅ - -**File**: `tests/e2e/browser/visual-regression.spec.js` - -**Coverage**: - -- Dashboard visual snapshot -- Analytics page visual snapshot -- Backups page visual snapshot -- Players page visual snapshot -- Worlds page visual snapshot -- Login page visual snapshot - -**Framework**: Playwright with screenshot comparison - -### 4. Accessibility Tests ✅ - -**File**: `web/src/test/a11y.test.jsx` - -**Coverage**: - -- Analytics page accessibility (WCAG compliance) -- Dashboard page accessibility -- Backups page accessibility -- Players page accessibility -- Worlds page accessibility -- Login page accessibility -- Form label validation - -**Framework**: jest-axe - -### 5. Browser Automation with Playwright ✅ - -**Files**: - -- `playwright.config.js` - Playwright configuration -- `tests/e2e/browser/analytics.spec.js` - Analytics browser tests -- `tests/e2e/browser/user-journey.spec.js` - User journey browser tests -- `tests/e2e/browser/visual-regression.spec.js` - Visual regression tests -- `.github/workflows/playwright.yml` - CI/CD integration - -**Coverage**: - -- Real browser testing (Chromium, Firefox, WebKit) -- Complete user workflows -- Visual regression testing -- Cross-browser compatibility - -## Test Statistics - -### Total Test Files Created/Updated - -- **New Test Files**: 15+ -- **Updated Test Files**: 5+ -- **Total Test Cases**: 250+ - -### Breakdown by Type - -- **API Tests**: 80+ test cases -- **Component Tests**: 60+ test cases -- **Integration Tests**: 25+ test cases -- **E2E Tests**: 40+ test cases -- **Unit Tests (Scripts)**: 20+ test cases -- **Accessibility Tests**: 7+ test cases -- **Visual Tests**: 6+ test cases -- **Browser Tests**: 15+ test cases - -## Coverage Improvements - -### Before All Additions - -- **Overall Coverage**: ~51% -- **API Coverage**: ~40% -- **Component Coverage**: ~20% -- **E2E Coverage**: ~15% -- **Analytics Coverage**: 0% - -### After All Additions - -- **Overall Coverage**: ~70%+ ✅ -- **API Coverage**: ~75%+ ✅ -- **Component Coverage**: ~70%+ ✅ -- **E2E Coverage**: ~55%+ ✅ -- **Analytics Coverage**: ~95%+ ✅ - -## New Test Files - -### Analytics Tests - -1. ✅ `tests/api/test_analytics.py` - API endpoint tests -2. ✅ `tests/api/test_analytics_processor.py` - Algorithm unit tests -3. ✅ `web/src/pages/__tests__/Analytics.test.jsx` - Component tests -4. ✅ `web/src/test/integration/analytics.integration.test.jsx` - Integration tests -5. ✅ `tests/integration/test-analytics.sh` - System integration -6. ✅ `tests/e2e/test-analytics-workflow.sh` - E2E workflow -7. ✅ `tests/unit/test-analytics-collector.sh` - Collector unit tests -8. ✅ `tests/e2e/browser/analytics.spec.js` - Browser tests - -### Component Tests - -9. ✅ `web/src/pages/__tests__/Backups.test.jsx` - Backups component -10. ✅ `web/src/pages/__tests__/Players.test.jsx` - Players component -11. ✅ `web/src/pages/__tests__/Worlds.test.jsx` - Worlds component - -### E2E Tests - -12. ✅ `tests/e2e/test-complete-user-journey.sh` - Complete journey -13. ✅ `tests/e2e/test-web-ui-workflow.sh` - Web UI workflow -14. ✅ `tests/e2e/browser/user-journey.spec.js` - Browser journey - -### Accessibility & Visual - -15. ✅ `web/src/test/a11y.test.jsx` - Accessibility tests -16. ✅ `tests/e2e/browser/visual-regression.spec.js` - Visual tests - -### Comprehensive API Tests - -17. ✅ `tests/api/test_api_comprehensive.py` - Functional API tests - -## Running All Tests - -### Complete Test Suite - -```bash -# All tests -make test - -# Specific test types -make test-api # API tests only -make test-web # Web UI tests only -make test-web-a11y # Accessibility tests -make test-playwright # Browser tests -make test-e2e # E2E tests -``` - -### Individual Test Suites - -```bash -# Python tests -pytest tests/api/ -v - -# Component tests -cd web && npm test - -# Browser tests -cd web && npm run test:playwright - -# Accessibility -cd web && npm run test:a11y - -# Visual regression -cd web && npx playwright test tests/e2e/browser/visual-regression.spec.js -``` - -## Test Configuration - -### Playwright - -- **Config**: `playwright.config.js` -- **Browsers**: Chromium, Firefox, WebKit -- **Screenshots**: On failure -- **Traces**: On first retry - -### Vitest - -- **Config**: `web/vitest.config.js` -- **Environment**: jsdom -- **Coverage**: v8 provider -- **Setup**: Includes jest-axe matchers - -### Pytest - -- **Config**: `tests/api/pytest.ini` -- **Coverage**: pytest-cov -- **Markers**: unit, integration, api, slow - -## CI/CD Integration - -### GitHub Actions Workflows - -- ✅ `.github/workflows/tests.yml` - Main test workflow -- ✅ `.github/workflows/coverage.yml` - Coverage reporting -- ✅ `.github/workflows/playwright.yml` - Browser tests (NEW) - -### Test Execution - -- Runs on all pull requests -- Runs on pushes to main -- Generates coverage reports -- Publishes test results -- Screenshots on failure - -## Documentation - -### New Documentation Files - -1. ✅ `docs/TESTING_COMPLETE.md` - Complete testing guide -2. ✅ `docs/WEB_UI_TESTING.md` - Web UI testing guide -3. ✅ `docs/TEST_COVERAGE.md` - Coverage guide -4. ✅ `tests/ANALYTICS_TESTS.md` - Analytics tests summary -5. ✅ `tests/TEST_SUMMARY.md` - Test summary -6. ✅ `tests/COMPLETE_TEST_SUMMARY.md` - This document -7. ✅ `tests/e2e/browser/README.md` - Browser tests guide - -## Test Quality Metrics - -### Coverage Goals - -- ✅ **Overall**: 70%+ (target: 70%) - ACHIEVED -- ✅ **API**: 75%+ (target: 75%) - ACHIEVED -- ✅ **Components**: 70%+ (target: 70%) - ACHIEVED -- ✅ **E2E**: 55%+ (target: 50%) - EXCEEDED -- ✅ **Analytics**: 95%+ (target: 80%) - EXCEEDED - -### Test Execution - -- **Unit Tests**: < 5 seconds -- **Component Tests**: < 10 seconds -- **Integration Tests**: < 15 seconds -- **E2E Tests**: < 30 seconds (when not skipped) -- **Browser Tests**: < 60 seconds - -### Test Reliability - -- **Flaky Tests**: 0 -- **Skipped Tests**: E2E tests (require running server) -- **Failing Tests**: 0 - -## Key Achievements - -### ✅ Complete Test Coverage - -- All major features have comprehensive tests -- Analytics system fully tested -- Web UI components tested -- E2E workflows validated - -### ✅ Quality Assurance - -- Accessibility compliance (WCAG) -- Visual regression prevention -- Cross-browser compatibility -- Error handling validation - -### ✅ Developer Experience - -- Easy test execution -- Clear test organization -- Comprehensive documentation -- CI/CD integration - -## Next Steps (Future Enhancements) - -### Performance Testing - -- Load testing -- Stress testing -- Performance benchmarks - -### Security Testing - -- Penetration testing -- Security vulnerability scanning -- OWASP compliance - -### Advanced Testing - -- Mutation testing -- Property-based testing -- Contract testing - -## See Also - -- [Testing Guide](README.md) -- [Complete Testing Guide](../docs/TESTING_COMPLETE.md) -- [Web UI Testing Guide](../docs/WEB_UI_TESTING.md) -- [Test Coverage Guide](../docs/TEST_COVERAGE.md) -- [Analytics Tests](ANALYTICS_TESTS.md) - ---- - -**Status**: ✅ All optional next steps completed! -**Coverage**: ~70%+ overall (exceeds 60% target) -**Test Cases**: 250+ comprehensive tests -**Last Updated**: 2025-01-27 diff --git a/tests/README.md b/tests/README.md index b66d0fa..f09835b 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,189 +1,50 @@ -# Testing Guide +# Tests -This directory contains automated tests for the Minecraft Server project. +The full testing guide lives in [docs/TESTING.md](../docs/TESTING.md); web-specific +details are in [docs/WEB_UI_TESTING.md](../docs/WEB_UI_TESTING.md). This file just +maps the directory. -## Test Structure +## Layout ``` tests/ -├── unit/ # Unit tests for individual scripts -├── integration/ # Integration tests -├── api/ # API endpoint tests -├── e2e/ # End-to-end tests for complete workflows -├── helpers/ # Test utilities and helpers -│ ├── test-utils.sh # Common test functions -│ ├── mock-server.sh # Mock server for testing -│ ├── bats-support/ # BATS support library -│ └── bats-assert/ # BATS assertion library -└── fixtures/ # Test data and fixtures +├── api/ pytest suite for the Flask API — run from THIS directory +│ (tests/api/pytest.ini holds the coverage flags and markers) +├── unit/ BATS unit tests for individual shell scripts +├── integration/ BATS integration tests across scripts +├── e2e/ BATS end-to-end workflows (need a running server) +└── helpers/ Shared test utilities, mock server, BATS support libraries ``` -## Running Tests +Playwright browser tests live in [`web/tests/e2e/`](../web/tests/e2e/), and React +unit tests sit beside their components in `web/src/**/__tests__/`. -### Run All Tests +## Running ```bash -./scripts/run-tests.sh +make test # syntax checks + pytest + vitest +make test-api # pytest only +make test-web # vitest only +make test-playwright # Playwright browser tests +make test-e2e # BATS end-to-end +make coverage # pytest with a coverage report ``` -### Run Specific Test Suite +Or directly: ```bash -# Unit tests only -./scripts/run-tests.sh unit - -# Integration tests only -./scripts/run-tests.sh integration - -# API tests only -./scripts/run-tests.sh api - -# E2E tests only -./scripts/run-tests.sh e2e -``` - -### Run Individual Test - -```bash -# Bash test -bash tests/unit/test-manage.sh - -# Python test -python3 -m pytest tests/api/test_api.py -``` - -## Test Requirements - -### Bash Tests - -- `bats` (Bash Automated Testing System) - for bash script tests -- Standard bash utilities - -### Python Tests - -- `pytest` - Python testing framework -- `requests` - For API testing - -Install dependencies: - -```bash -./scripts/run-tests.sh install-deps -``` - -## Writing Tests - -### Bash Script Tests - -Create test file: `tests/unit/test-.sh` - -```bash -#!/usr/bin/env bats - -load 'helpers/bats-support/load' -load 'helpers/bats-assert/load' - -@test "script does something" { - run ./scripts/script.sh command - assert_success - assert_output --partial "expected output" -} -``` - -### End-to-End Tests - -Create E2E test file: `tests/e2e/test-.sh` - -```bash -#!/usr/bin/env bats - -load 'helpers/bats-support/load' -load 'helpers/bats-assert/load' -load 'helpers/test-utils.sh' - -@test "complete workflow test" { - # Test complete workflow - run some_command - assert_success -} -``` - -### Python Tests - -Create test file: `tests/api/test_.py` - -```python -import pytest -from api.server import app - -def test_endpoint(client): - response = client.get('/api/health') - assert response.status_code == 200 -``` - -## Test Utilities - -### test-utils.sh - -Common test functions: - -- `create_test_dir()` - Create temporary test directory -- `wait_for_server()` - Wait for server to be ready -- `create_test_backup()` - Create test backup file -- `api_request()` - Make authenticated API request -- `assert_file_exists()` - Assert file exists -- `assert_file_contains()` - Assert file contains text - -### mock-server.sh - -Mock Minecraft server for testing: - -- `start_mock_server` - Start mock server -- `stop_mock_server` - Stop mock server -- `status_mock_server` - Check server status - -Usage: - -```bash -source tests/helpers/mock-server.sh -start_mock_server -# Run tests -stop_mock_server -``` - -## CI/CD Integration - -Tests run automatically on: - -- Pull requests -- Pushes to main branch -- Manual workflow dispatch - -See `.github/workflows/tests.yml` for configuration. - -## Test Coverage - -Run tests with coverage: - -```bash -# Python tests with coverage -pytest tests/api/ --cov=api --cov-report=html - -# View coverage report -open htmlcov/index.html - -# Web UI tests with coverage -cd web -npm run test:coverage - -# Check coverage threshold -./scripts/check-coverage.sh check +./scripts/run-tests.sh [unit|integration|api|e2e] +cd tests/api && pytest -v +cd tests/api && pytest -v -m performance # markers: unit, integration, api, + # slow, performance, contract, e2e +bats tests/unit/test-manage.sh ``` -## Current Coverage Status +## Requirements -- **API Tests**: ~65% coverage -- **Web UI Component Tests**: ~50% coverage -- **E2E Workflows**: ~40% coverage -- **Overall Coverage**: ~65%+ (target: 70%) +- `bats` plus `bats-support` / `bats-assert` (vendored in `helpers/`) for shell tests +- Python dependencies from `api/requirements-test.txt` +- `cd web && npm install` for Vitest and Playwright -See [TEST_COVERAGE.md](../docs/TEST_COVERAGE.md) for detailed coverage information. +`--strict-markers` is enabled, so a new pytest marker must be registered in +`tests/api/pytest.ini` and `pyproject.toml` before it can be used. diff --git a/tests/TEST_SUMMARY.md b/tests/TEST_SUMMARY.md deleted file mode 100644 index f84e898..0000000 --- a/tests/TEST_SUMMARY.md +++ /dev/null @@ -1,234 +0,0 @@ -# Test Coverage Summary - -This document summarizes all tests added to improve coverage, including web UI component tests and E2E workflows. - -## New Tests Added - -### 1. Analytics Component Tests ✅ - -**File**: `web/src/pages/__tests__/Analytics.test.jsx` - -**Coverage**: - -- Component rendering (title, loading states) -- Tab navigation (overview, performance, players, anomalies, predictions) -- Time period selection -- Data collection button -- Report generation button -- Warnings and recommendations display -- Error handling -- Periodic data updates - -**Test Cases**: 15+ comprehensive tests - -### 2. Analytics Integration Tests ✅ - -**File**: `web/src/test/integration/analytics.integration.test.jsx` - -**Coverage**: - -- Complete data loading workflow -- Multi-step user interactions -- Tab navigation workflow -- Period change and refresh -- Anomaly detection display - -**Test Cases**: 4 integration scenarios - -### 3. Complete User Journey E2E Tests ✅ - -**File**: `tests/e2e/test-complete-user-journey.sh` - -**Coverage**: - -- Registration → Login → Dashboard → Analytics -- Server management workflow -- Backup management workflow -- Analytics → Report → Action workflow -- Configuration management -- World management -- Error handling scenarios - -**Test Cases**: 9 complete workflows - -### 4. Web UI Workflow E2E Tests ✅ - -**File**: `tests/e2e/test-web-ui-workflow.sh` - -**Coverage**: - -- Login page access -- Registration workflow -- Dashboard data loading -- Analytics navigation workflow -- Backup management via API -- Player management via API -- Error handling -- Session management - -**Test Cases**: 8 UI workflow scenarios - -### 5. Analytics API Tests ✅ - -**File**: `tests/api/test_analytics.py` (Previously created) - -**Coverage**: All analytics endpoints with comprehensive test cases - -### 6. Comprehensive API Tests ✅ - -**File**: `tests/api/test_api_comprehensive.py` (Previously created) - -**Coverage**: Functional tests beyond authentication - -## Test Coverage Improvements - -### Before - -- **Web UI Component Tests**: ~20% (only basic components) -- **E2E Workflows**: ~15% (mostly skipped/placeholder) -- **Analytics Tests**: 0% -- **Overall Coverage**: ~51% - -### After - -- **Web UI Component Tests**: ~50% (+30%) -- **E2E Workflows**: ~40% (+25%) -- **Analytics Tests**: ~95% (+95%) -- **Overall Coverage**: ~65%+ (+14%+) - -## Test Statistics - -### New Test Files - -- `web/src/pages/__tests__/Analytics.test.jsx` - 15+ test cases -- `web/src/test/integration/analytics.integration.test.jsx` - 4 test cases -- `tests/e2e/test-complete-user-journey.sh` - 9 test cases -- `tests/e2e/test-web-ui-workflow.sh` - 8 test cases - -### Total New Tests - -- **Component Tests**: 15+ -- **Integration Tests**: 4 -- **E2E Tests**: 17 -- **Total**: 36+ new test cases - -## Running the Tests - -### Web UI Tests - -```bash -cd web -npm test # All tests -npm test Analytics # Analytics tests only -npm test integration # Integration tests only -npm run test:coverage # With coverage -``` - -### E2E Tests - -```bash -# Complete user journey -bats tests/e2e/test-complete-user-journey.sh - -# Web UI workflows -bats tests/e2e/test-web-ui-workflow.sh - -# Analytics workflow -bats tests/e2e/test-analytics-workflow.sh -``` - -### All Tests - -```bash -./scripts/run-tests.sh -``` - -## Test Coverage by Area - -### Analytics System - -- ✅ API endpoint tests (95%) -- ✅ Component tests (90%) -- ✅ Integration tests (85%) -- ✅ E2E workflow tests (90%) -- ✅ Unit tests for scripts (80%) - -### Web UI Components - -- ✅ Analytics component (90%) -- ⚠️ Dashboard component (60%) -- ⚠️ Other components (40%) - -### E2E Workflows - -- ✅ Complete user journey (80%) -- ✅ Analytics workflow (85%) -- ✅ Web UI workflows (75%) -- ⚠️ Other workflows (30%) - -## Next Steps - -### High Priority - -1. ✅ Analytics component tests - DONE -2. ✅ Analytics integration tests - DONE -3. ✅ E2E workflow tests - DONE -4. ⚠️ Analytics processor unit tests (Python) - PENDING -5. ⚠️ More component tests (Backups, Players, Worlds pages) - -### Medium Priority - -6. Visual regression tests -7. Accessibility tests -8. Performance tests -9. Browser automation (Playwright/Cypress) - -### Low Priority - -10. Visual snapshot tests -11. Mobile responsive tests -12. Cross-browser tests - -## Test Quality Metrics - -### Code Coverage - -- **Statements**: 65%+ (target: 70%) -- **Branches**: 60%+ (target: 65%) -- **Functions**: 70%+ (target: 75%) -- **Lines**: 65%+ (target: 70%) - -### Test Execution - -- **Unit Tests**: < 5 seconds -- **Integration Tests**: < 10 seconds -- **E2E Tests**: < 30 seconds (when not skipped) - -### Test Reliability - -- **Flaky Tests**: 0 -- **Skipped Tests**: E2E tests (require running server) -- **Failing Tests**: 0 - -## Documentation - -- ✅ `docs/WEB_UI_TESTING.md` - Web UI testing guide -- ✅ `docs/TEST_COVERAGE.md` - Test coverage guide -- ✅ `tests/ANALYTICS_TESTS.md` - Analytics tests summary -- ✅ `tests/TEST_SUMMARY.md` - This document - -## CI/CD Integration - -All new tests are integrated into CI/CD: - -- Run on pull requests -- Run on pushes to main -- Coverage reports generated -- Test results published - -## See Also - -- [Testing Guide](README.md) -- [Web UI Testing Guide](../docs/WEB_UI_TESTING.md) -- [Test Coverage Guide](../docs/TEST_COVERAGE.md) -- [Analytics Tests](ANALYTICS_TESTS.md) diff --git a/tests/e2e/browser/README.md b/tests/e2e/browser/README.md deleted file mode 100644 index 97f0f1e..0000000 --- a/tests/e2e/browser/README.md +++ /dev/null @@ -1,134 +0,0 @@ -# Browser E2E Tests - -Browser automation tests using Playwright for real browser testing. - -## Setup - -### Install Dependencies - -```bash -cd web -npm install -npx playwright install -``` - -### Configuration - -- **Config File**: `playwright.config.js` -- **Browsers**: Chromium, Firefox, WebKit -- **Base URL**: http://localhost:5173 - -## Running Tests - -### All Browser Tests - -```bash -cd web -npx playwright test -``` - -### Specific Test File - -```bash -cd web -npx playwright test tests/e2e/analytics.spec.js -``` - -**Note**: Test files have been moved from `tests/e2e/browser/` to `web/tests/e2e/` to ensure proper module resolution. - -### With UI - -```bash -npx playwright test --ui -``` - -### Visual Regression - -```bash -npx playwright test tests/e2e/browser/visual-regression.spec.js -``` - -### Update Snapshots - -```bash -npx playwright test --update-snapshots -``` - -## Test Files - -### analytics.spec.js - -Tests for Analytics page: - -- Page loading -- Tab navigation -- Time period selection -- Data collection -- Report generation - -### user-journey.spec.js - -Complete user journey tests: - -- Registration → Login → Dashboard -- Navigation through all pages -- Server management - -### visual-regression.spec.js - -Visual regression tests: - -- Dashboard snapshot -- Analytics page snapshot -- Backups page snapshot -- Players page snapshot -- Worlds page snapshot -- Login page snapshot - -## Writing Tests - -### Basic Test Structure - -```javascript -import { test, expect } from '@playwright/test'; - -test('test description', async ({ page }) => { - await page.goto('/path'); - await expect(page.getByText('Expected')).toBeVisible(); -}); -``` - -### Mocking API - -```javascript -await page.route('**/api/endpoint', async route => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ data: 'value' }), - }); -}); -``` - -### Visual Snapshots - -```javascript -await expect(page).toHaveScreenshot('filename.png', { - fullPage: true, - maxDiffPixels: 100, -}); -``` - -## CI/CD - -Browser tests run in CI/CD: - -- On pull requests -- On pushes to main -- Screenshots on failure -- HTML reports generated - -## See Also - -- [Playwright Documentation](https://playwright.dev/) -- [Testing Guide](../../README.md) diff --git a/tests/e2e/browser/analytics.spec.js b/tests/e2e/browser/analytics.spec.js deleted file mode 100644 index 9faa296..0000000 --- a/tests/e2e/browser/analytics.spec.js +++ /dev/null @@ -1,150 +0,0 @@ -import { expect, test } from '@playwright/test'; - -test.describe('Analytics Page', () => { - test.beforeEach(async ({ page }) => { - // Mock API responses - await page.route('**/api/analytics/report*', async route => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ - report: { - generated_at: '2024-01-27T12:00:00', - period_hours: 24, - player_behavior: { - unique_players: 5, - peak_hour: 20, - hourly_distribution: { 20: 10, 21: 8 }, - }, - performance: { - tps: { - current: 20.0, - average: 19.8, - trend: { direction: 'stable' }, - }, - cpu: { current: 50.0 }, - memory: { current: 1000 }, - }, - summary: { - status: 'healthy', - warnings: [], - recommendations: [], - }, - }, - }), - }); - }); - - await page.route('**/api/analytics/trends*', async route => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ - trends: { - tps: { current: 20.0, trend: { direction: 'stable' } }, - cpu: { current: 50.0 }, - memory: { current: 1000 }, - }, - }), - }); - }); - - await page.route('**/api/analytics/anomalies*', async route => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ anomalies: [] }), - }); - }); - - await page.route('**/api/analytics/predictions*', async route => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ - prediction: { predicted: 1200, confidence: 85.0 }, - }), - }); - }); - - await page.route('**/api/analytics/player-behavior*', async route => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ - behavior: { unique_players: 5, peak_hour: 20 }, - }), - }); - }); - - // Mock authentication - await page.goto('/analytics'); - await page.evaluate(() => { - localStorage.setItem('api_key', 'test-api-key'); - }); - }); - - test('should load analytics dashboard', async ({ page }) => { - await page.goto('/analytics'); - await expect(page.getByText('Analytics Dashboard')).toBeVisible(); - }); - - test('should display overview tab by default', async ({ page }) => { - await page.goto('/analytics'); - await expect(page.getByText('Summary')).toBeVisible(); - await expect(page.getByText('Current TPS')).toBeVisible(); - }); - - test('should switch to performance tab', async ({ page }) => { - await page.goto('/analytics'); - await page.click('button:has-text("Performance")'); - await expect(page.getByText('TPS (Ticks Per Second)')).toBeVisible(); - }); - - test('should switch to players tab', async ({ page }) => { - await page.goto('/analytics'); - await page.click('button:has-text("Players")'); - await expect(page.getByText('Player Behavior')).toBeVisible(); - }); - - test('should change time period', async ({ page }) => { - await page.goto('/analytics'); - await page.selectOption('select', '6'); - await expect(page.getByText('Summary')).toBeVisible(); - }); - - test('should collect analytics data', async ({ page }) => { - let collectCalled = false; - await page.route('**/api/analytics/collect', async route => { - collectCalled = true; - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ success: true, message: 'Data collected' }), - }); - }); - - await page.goto('/analytics'); - await page.click('button:has-text("Collect Data")'); - await expect(collectCalled).toBeTruthy(); - }); - - test('should generate custom report', async ({ page }) => { - let generateCalled = false; - await page.route('**/api/analytics/custom-report', async route => { - generateCalled = true; - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ - report: {}, - saved_as: 'custom_report.json', - }), - }); - }); - - await page.goto('/analytics'); - await page.click('button:has-text("Generate Report")'); - await expect(generateCalled).toBeTruthy(); - }); -}); diff --git a/tests/e2e/browser/user-journey.spec.js b/tests/e2e/browser/user-journey.spec.js deleted file mode 100644 index 39a6fcd..0000000 --- a/tests/e2e/browser/user-journey.spec.js +++ /dev/null @@ -1,88 +0,0 @@ -import { expect, test } from '@playwright/test'; - -test.describe('Complete User Journey', () => { - test('user can register, login, and access dashboard', async ({ page }) => { - const testUser = `testuser_${Date.now()}`; - const testPassword = 'TestPassword123!'; - - // Step 1: Register - await page.goto('/register'); - await page.fill('input[name="username"]', testUser); - await page.fill('input[name="password"]', testPassword); - await page.fill('input[name="confirmPassword"]', testPassword); - await page.click('button:has-text("Register")'); - - // Step 2: Login - await page.goto('/login'); - await page.fill('input[name="username"]', testUser); - await page.fill('input[name="password"]', testPassword); - await page.click('button:has-text("Login")'); - - // Step 3: Access Dashboard - await page.waitForURL('/dashboard'); - await expect(page.getByText('Dashboard')).toBeVisible(); - }); - - test('user can navigate through all main pages', async ({ page }) => { - // Mock authentication - await page.evaluate(() => { - localStorage.setItem('api_key', 'test-api-key'); - }); - - // Mock API responses - await page.route('**/api/**', async route => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({}), - }); - }); - - await page.goto('/dashboard'); - await expect(page.getByText('Dashboard')).toBeVisible(); - - // Navigate to Analytics - await page.click('a:has-text("Analytics")'); - await expect(page.getByText('Analytics Dashboard')).toBeVisible(); - - // Navigate to Players - await page.click('a:has-text("Players")'); - await expect(page.getByText('Player Management')).toBeVisible(); - - // Navigate to Backups - await page.click('a:has-text("Backups")'); - await expect(page.getByText(/backup/i)).toBeVisible(); - - // Navigate to Worlds - await page.click('a:has-text("Worlds")'); - await expect(page.getByText('World Management')).toBeVisible(); - }); - - test('user can manage server from dashboard', async ({ page }) => { - await page.evaluate(() => { - localStorage.setItem('api_key', 'test-api-key'); - }); - - let startCalled = false; - await page.route('**/api/server/start', async route => { - startCalled = true; - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ success: true }), - }); - }); - - await page.route('**/api/status', async route => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ running: false, status: 'Stopped' }), - }); - }); - - await page.goto('/dashboard'); - await page.click('button:has-text("Start Server")'); - await expect(startCalled).toBeTruthy(); - }); -}); diff --git a/tests/e2e/browser/visual-regression.spec.js b/tests/e2e/browser/visual-regression.spec.js deleted file mode 100644 index ec60226..0000000 --- a/tests/e2e/browser/visual-regression.spec.js +++ /dev/null @@ -1,79 +0,0 @@ -import { expect, test } from '@playwright/test'; - -test.describe('Visual Regression Tests', () => { - test.beforeEach(async ({ page }) => { - // Mock API responses - await page.route('**/api/**', async route => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ - running: true, - status: 'Up', - players: [], - backups: [], - worlds: [], - metrics: {}, - }), - }); - }); - - await page.evaluate(() => { - localStorage.setItem('api_key', 'test-api-key'); - }); - }); - - test('dashboard visual snapshot', async ({ page }) => { - await page.goto('/dashboard'); - await page.waitForLoadState('networkidle'); - await expect(page).toHaveScreenshot('dashboard.png', { - fullPage: true, - maxDiffPixels: 100, - }); - }); - - test('analytics page visual snapshot', async ({ page }) => { - await page.goto('/analytics'); - await page.waitForLoadState('networkidle'); - await expect(page).toHaveScreenshot('analytics.png', { - fullPage: true, - maxDiffPixels: 100, - }); - }); - - test('backups page visual snapshot', async ({ page }) => { - await page.goto('/backups'); - await page.waitForLoadState('networkidle'); - await expect(page).toHaveScreenshot('backups.png', { - fullPage: true, - maxDiffPixels: 100, - }); - }); - - test('players page visual snapshot', async ({ page }) => { - await page.goto('/players'); - await page.waitForLoadState('networkidle'); - await expect(page).toHaveScreenshot('players.png', { - fullPage: true, - maxDiffPixels: 100, - }); - }); - - test('worlds page visual snapshot', async ({ page }) => { - await page.goto('/worlds'); - await page.waitForLoadState('networkidle'); - await expect(page).toHaveScreenshot('worlds.png', { - fullPage: true, - maxDiffPixels: 100, - }); - }); - - test('login page visual snapshot', async ({ page }) => { - await page.goto('/login'); - await page.waitForLoadState('networkidle'); - await expect(page).toHaveScreenshot('login.png', { - fullPage: true, - maxDiffPixels: 100, - }); - }); -}); diff --git a/web/playwright-report/index.html b/web/playwright-report/index.html deleted file mode 100644 index 72914ee..0000000 --- a/web/playwright-report/index.html +++ /dev/null @@ -1,85 +0,0 @@ - - - - - - - - - Playwright Test Report - - - - -
- - - \ No newline at end of file From 6eaeaad134223b723c8ea9bf83c29ff2e6703465 Mon Sep 17 00:00:00 2001 From: Matthew Anderson Date: Sat, 19 Sep 2026 00:36:19 -0500 Subject: [PATCH 2/2] fix: correct SERVER_TYPE values and wire up the coverage config Addresses both findings from the Copilot review. .env.example advertised `spigot` and `forge` as SERVER_TYPE values. The dispatcher in scripts/download-server.sh handles only vanilla, paper and fabric; `spigot` exits 1 with a pointer to BuildTools and `forge` falls through to "Unknown server type". Corrected the list and explained what spigot and Forge actually require. docs/UPDATE_MANAGEMENT.md carried the same claim about spigot and is fixed too. .coverage-config.ini is not a filename coverage.py auto-discovers, and coverage only reads config from the current directory. Every documented entry point runs from tests/api, so the root pyproject.toml was never reached from there -- verified by planting broad exclude_lines in it and seeing the statement count stay at 2230 with cwd=tests/api, while dropping to 66 with cwd=repo root. The practical effect was that `make test-api` and the documented `cd tests/api && pytest -v` applied no exclusions and no fail_under, which predates this branch. Adding --cov-config to tests/api/pytest.ini fixes that and makes every entry point agree with the Makefile and CI, which already passed the flag explicitly. Before: TOTAL 2230 1293 42%, no threshold check. After: TOTAL 2220 1284 42.16%, "Required test coverage of 40.0% reached". Verified: 221 pytest tests pass via `make test-api`, eslint clean, compose validates, all scripts pass bash -n, 0 broken markdown links. Co-Authored-By: Claude Opus 5 --- .env.example | 6 +++++- AGENTS.md | 4 +++- CHANGELOG.md | 5 ++++- docs/TESTING.md | 5 +++++ docs/UPDATE_MANAGEMENT.md | 2 +- tests/api/pytest.ini | 6 ++++++ 6 files changed, 24 insertions(+), 4 deletions(-) diff --git a/.env.example b/.env.example index 090bbc7..d55dee7 100644 --- a/.env.example +++ b/.env.example @@ -4,7 +4,11 @@ # --- Minecraft server ------------------------------------------------------ MINECRAFT_VERSION=1.20.4 -SERVER_TYPE=vanilla # vanilla | paper | spigot | fabric | forge +# vanilla | paper | fabric -- these are what scripts/download-server.sh can +# fetch. "spigot" is recognised but exits with a pointer to BuildTools, which +# you must run yourself; Forge/Quilt servers are detected by +# scripts/mod-loader-detector.sh once installed, but are not downloaded here. +SERVER_TYPE=vanilla SERVER_PORT=25565 EULA=TRUE # you must accept https://www.minecraft.net/eula TZ=UTC diff --git a/AGENTS.md b/AGENTS.md index ee5004c..db765ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -157,7 +157,9 @@ wrapper from `scripts/lib/common.sh`. `web/src/test/integration/`; MSW handlers in `web/src/test/mocks/`. - Playwright specs belong in `web/tests/e2e/` only. - BATS suites in `tests/unit/`, `tests/integration/`, `tests/e2e/`. -- Coverage threshold is enforced at **40%** in `.coverage-config.ini`. +- Coverage threshold is enforced at **40%** in `.coverage-config.ini`. That file is + not auto-discovered by coverage.py, so every entry point passes `--cov-config` + explicitly; run pytest from `tests/api` so the relative path resolves. See [docs/TESTING.md](docs/TESTING.md) for the full guide. diff --git a/CHANGELOG.md b/CHANGELOG.md index feee4fb..a9548ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,7 +25,10 @@ All notable changes to this project will be documented in this file. - Added `.env.example` (referenced by the `Makefile` but previously missing). - Synced the pytest markers in `pyproject.toml` with `tests/api/pytest.ini`, and removed the duplicate `[tool.coverage]` block so `.coverage-config.ini` is the - only coverage config. + only coverage config. Added the matching `--cov-config` to + `tests/api/pytest.ini`, since that filename is not auto-discovered by + coverage.py — `make test-api` and a bare `cd tests/api && pytest` had been + running with no exclusions and no `fail_under` at all. - Tightened `.gitignore`: added `.mypy_cache/`, `playwright-report/`, `test-results/`; fixed an inline comment that made a negation pattern literal. diff --git a/docs/TESTING.md b/docs/TESTING.md index 9d9a157..3a8aca8 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -243,6 +243,11 @@ Coverage is measured for the Python API with `coverage.py`, configured in in that file as coverage grows. `scripts/check-coverage.sh` honours the same value via `COVERAGE_THRESHOLD`. +That filename is not one coverage.py discovers on its own, so every entry point +passes it explicitly with `--cov-config` — `tests/api/pytest.ini`, the `Makefile` +targets, CI, and the helper scripts. Run pytest from `tests/api` so the relative +path resolves. + ### Running coverage ```bash diff --git a/docs/UPDATE_MANAGEMENT.md b/docs/UPDATE_MANAGEMENT.md index d48d2b4..e376867 100644 --- a/docs/UPDATE_MANAGEMENT.md +++ b/docs/UPDATE_MANAGEMENT.md @@ -207,7 +207,7 @@ Set server type in `docker-compose.yml` or `.env`: ```yaml environment: - - SERVER_TYPE=paper # vanilla, paper, spigot, or fabric + - SERVER_TYPE=paper # vanilla, paper or fabric (spigot needs BuildTools) ``` Or in `.env`: diff --git a/tests/api/pytest.ini b/tests/api/pytest.ini index 2387fc0..9094b53 100644 --- a/tests/api/pytest.ini +++ b/tests/api/pytest.ini @@ -3,11 +3,17 @@ testpaths = . python_files = test_*.py python_classes = Test* python_functions = test_* +# --cov-config is required: .coverage-config.ini is not one of the filenames +# coverage.py auto-discovers, and coverage only looks in the current directory, +# which is tests/api for every documented entry point. Without the flag the +# exclusions and fail_under are silently skipped. The Makefile and CI pass the +# same path. addopts = -v --strict-markers --tb=short --cov=api + --cov-config=../../.coverage-config.ini --cov-report=term-missing --cov-report=html:htmlcov --cov-report=xml:coverage.xml