diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..6777be5 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Rage87 - rage87@geigernet.eu + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, +DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE +OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/RADME.md b/RADME.md new file mode 100644 index 0000000..2bad1cb --- /dev/null +++ b/RADME.md @@ -0,0 +1,170 @@ +# Luanti-Web: A dynamic website-toolkit + +Welcome to the Luanti Web Generator! Born from a passion for creative sandbox gaming, this hobby project provides a powerful, automated toolkit for generating a beautiful and feature-rich static website for your Minetest or Luanti server. Showcase your server, worlds, track your players, and inform your community. + +This system is designed from the ground up to be modular, easily configurable, and perfect for small communities who want web presence without the hassle. + +--- + +# ✨ Features + +* **Automated Map Generation:** Leverages `minetestmapper` to create high-resolution PNG maps of your game worlds. +* **Tiled Map Generation:** Uses `gdal2tiles.py` to create performant, zoomable map tiles for a smooth user experience. +* **Dynamic Map Viewer:** Implements an interactive map viewer using [Leaflet.js](https://leafletjs.com/), powered by the generated map tiles. +* **Live Player Tracking:** Dynamically fetches and displays player locations as markers on the live map. +* **Map Archive:** Automatically saves a daily snapshot of the map and makes it available through a dropdown viewer on the world detail page. +* **Template-Driven Site Generation:** Builds all static HTML pages from simple, customizable templates. +* **Flexible Configuration:** Configuration is easy with a central global config and a sub-config file for every of your worlds. +* **Automation-Ready:** Designed for unattended execution via scheduling tools like cron. + +--- + +# 🔧 Prerequisites + +To run this system, the following software packages must be installed on your server: + +* **bash:** The scripting language used for the entire project. +* **ImageMagick:** Required for `identify` (to read image dimensions) and `convert` (to resize images). + * *Debian/Ubuntu Install:* `sudo apt-get install imagemagick` +* **GDAL/OGR:** Provides the `gdal2tiles.py` script for tile generation. + * *Debian/Ubuntu Install:* `sudo apt-get install gdal-bin python3-gdal` +* **minetestmapper:** The executable used to render maps from world data. This must be placed within the project directory. +* **Web Server:** A web server like Nginx or Apache is needed to serve the generated static files. + +--- + +# ⚙️ Installation & Setup + +### 1. Clone the Repository + +First, clone or copy all project files to a base directory on your server, such as `/opt/luweb/`. + +``` +git clone https://git.geigernet.eu/rainer/luanti-web.git /opt/luweb +cd /opt/luweb +chmod +x generate_map.sh generate_site.sh +``` + +### 2. Global Configuration + +The main configuration file is `config.sh`. You must edit this file to match your server's environment. + +**Key variables in `config.sh`:** + +* `BASE_SCRIPT_DIR`: The root directory of the project (e.g., `/opt/luweb`). +* `MINETESTMAPPER_WORLD_DATA_BASE_PATH`: The path to your Minetest/Luanti worlds' data directory (e.g., `/worlds/`), docker compatible. +* `WEB_ROOT_PATH`: The document root of your website where the generated files will be placed (e.g., `/var/www/your-domain.com/web`). +* `LOG_DIR_BASE`: The directory where log files will be written (e.g., `/var/log/luweb`). + +### 3. Per-World Configuration + +For each world you want to feature on the website, a `web.conf` file must exist within that world's data directory (e.g., `/worlds/my_world/web.conf`). This file allows you to override global defaults with world-specific settings. + +A minimal `web.conf` could look like this and is automatically created for every detected world in your `MINETESTMAPPER_WORLD_DATA_BASE_PATH`: + +```bash +# Display name for the world +WORLD_DISPLAY_NAME="My Creative World" + +# Server connection details +SERVER_ADDRESS="your-server.com" +SERVER_PORT="30001" + +# A short description for the world overview page +WORLD_SHORT_DESCRIPTION="A brief, catchy description of this world." + +# A detailed HTML description for the world's detail page +WORLD_LONG_DESCRIPTION="

A longer description with HTML support.

" +``` +--- + +## 📂 Directory Structure + +The system expects the following directory structure: +```md +/opt/luweb/ +├── config.sh +├── generate_map.sh +├── generate_site.sh +├── minetestmapper (executable) +├── site_generator/ +│ ├── templates/ +│ │ ├── world_detail_page.template +│ │ ├── world_detail_archive.template +│ │ └── ... +│ └── examples/ +│ └── web.conf.template +├── web_content/ +│ ├── images/ +│ │ └── players/ +│ └── static/ +│ ├── startseite_content.html +│ └── ... +└── worldmaps_output/ + └── / + ├── map.png + └── map_info.txt +``` +--- +# 🚀 Usage + +The scripts are designed to be run from the command line, either manually or via automated jobs. + +### 1. Map and Tile Generation + +The `generate_map.sh` script creates the map, tiles, and archive images for a specific world. It must be called with the "world key" (the name of the world's directory) as an argument. + +```bash +# Generate map assets for the world located in the 'world' directory +./generate_map.sh world +``` + +### 2. Website Generation + +The `generate_site.sh` script builds the entire website (overview, detail pages, etc.). It scans all configured world directories and creates a detail page for each one. + +```bash +# Generate the complete website +./generate_site.sh +``` + +### 3. Automation (Cronjob) + +For fully automatic operation, setting up cronjobs is recommended. + +**Example for `crontab -e`:** + +```bash +# Generate map assets for the 'world' every 30 minutes +*/30 * * * * /opt/luweb/generate_map.sh world >> /var/log/luweb/cron.log 2>&1 + +# Re-build the website every 12 hours +* */12 * * * /opt/luweb/generate_site.sh >> /var/log/luweb/cron.log 2>&1 +``` + +--- + +# 📄 License +**MIT License** +Copyright (c) 2025 Rage87 - rage87@geigernet.eu + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, +DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE +OR OTHER DEALINGS IN THE SOFTWARE. + +## 👤 Authors +* **Rage87** (Main-Developer) \ No newline at end of file