initial commital

2026-09-02 14:47:08 -06:00
commit 3c80aef53b
23 changed files with 1648 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,190 @@
+# Minecraft Podman Deployment (Ansible)
+
+Automated deployment of a Minecraft server running in a **Podman** container on a remote **Fedora** server using **Ansible**.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│              Ansible Control Node               │
+│  (your machine)                                 │
+│  ansible.cfg + site.yml + roles/                │
+└──────────────────────┬──────────────────────────┘
+                       │ SSH
+┌──────────────────────▼──────────────────────────┐
+│              Fedora Server                      │
+│  "external-apps"                                │
+│                                                 │
+│  ┌──────────────────────────────────────────┐   │
+│  │            Podman Container              │   │
+│  │  itzg/minecraft-server:latest (Paper)    │   │
+│  │  ┌────────────────────────────────────┐  │   │
+│  │  │  Minecraft Server (Java)           │  │   │
+│  │  └────────────────────────────────────┘  │   │
+│  └──────────────────────────────────────────┘   │
+│                                                 │
+│  systemd:  minecraft.service                    │
+│  systemd:  minecraft-backup.timer               │
+│  data:     /opt/minecraft/data                  │
+│  backups:  /opt/minecraft/backups               │
+└─────────────────────────────────────────────────┘
+```
+
+## Directory Structure
+
+```
+external-minecraft/
+├── ansible.cfg                    # Ansible configuration
+├── site.yml                       # Main deployment playbook
+├── uninstall.yml                  # Cleanup playbook
+├── requirements.yml               # Galaxy collections
+├── Makefile                       # Convenient wrapper
+├── inventory/
+│   └── hosts                      # Server inventory
+├── group_vars/
+│   └── all.yml                    # All configuration variables
+├── host_vars/                     # (optional) Per-host overrides
+└── roles/
+    └── minecraft-podman/
+        ├── tasks/main.yml         # All deployment tasks
+        ├── handlers/main.yml      # Service handlers
+        ├── templates/             # Jinja2 templates
+        │   ├── minecraft.service.j2
+        │   ├── minecraft.env.j2
+        │   ├── server.properties.j2
+        │   ├── Containerfile.j2
+        │   ├── backup.sh.j2
+        │   ├── restore.sh.j2
+        │   ├── health-check.sh.j2
+        │   └── jvm.opts.j2
+        └── defaults/main.yml      # Role defaults
+```
+
+## Prerequisites
+
+### On the control node (your machine)
+
+```bash
+# Fedora/RHEL/CentOS
+sudo dnf install python3-pip
+pip3 install --user ansible
+
+# or via pipx
+pipx install ansible
+
+# Debian/Ubuntu
+sudo apt install ansible
+```
+
+### Install Ansible collections
+
+```bash
+make install
+# or
+ansible-galaxy collection install -r requirements.yml
+```
+
+## Configuration
+
+Edit `group_vars/all.yml` to configure your server:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `minecraft.server_name` | Service/container name | `minecraft` |
+| `minecraft.version` | Server version | `latest` |
+| `minecraft.server_type` | Vanilla / Paper / etc. | `paper` |
+| `minecraft.java_memory` | Java heap size | `4G` |
+| `minecraft.max_players` | Max players | `20` |
+| `minecraft.port` | Minecraft port | `25565` |
+| `minecraft.rcon_password` | RCON password | `CHANGE_ME_NOW` |
+| `minecraft.motd` | Server message of day | Welcome message |
+| `paths.base_dir` | Install directory | `/opt/minecraft` |
+| `backup.enabled` | Enable automatic backups | `true` |
+
+**IMPORTANT**: Change `minecraft.rcon_password` before deploying.
+
+## Deployment
+
+```bash
+# Basic deployment
+make deploy
+
+# With explicit host
+make deploy LIMIT=external-apps
+
+# Or directly
+ansible-playbook site.yml --limit external-apps
+
+# Dry-run
+make check
+
+# Debug mode
+make debug
+```
+
+## Management
+
+```bash
+make status    # Check server status
+make logs      # View recent logs
+make restart   # Restart the server
+make stop      # Stop the server
+make start     # Start the server
+make backup    # Run backup immediately
+```
+
+## Connecting to the Server
+
+In Minecraft, use:
+```
+<server-ip>:<port>
+```
+
+For the default setup: `external-apps:25565`
+
+## Backups
+
+Backups run automatically every 6 hours (configurable in `group_vars/all.yml` under `backup.schedule`).
+
+- **Location**: `/opt/minecraft/backups/`
+- **Format**: `minecraft_YYYYMMDD_HHMMSS.tar.gz`
+- **Retention**: 10 backups (configurable)
+
+Restore with:
+```bash
+make restore
+```
+
+## Uninstall
+
+```bash
+make uninstall   # Interactive confirmation
+```
+
+Or manually:
+```bash
+ansible-playbook uninstall.yml --limit external-apps
+```
+
+## Advanced Configuration
+
+### Custom Server Type
+
+Set `minecraft.server_type` to:
+- `vanilla` - Official Mojang server
+- `paper` - High-performance fork (recommended)
+- `fabric` - Modding platform
+- `forge` - Classic modding
+- `purpur` - Paper fork with more features
+
+### Custom Container Image
+
+To use your own `Containerfile` instead of pulling a public image:
+1. Set `minecraft.use_custom_container: true` in `group_vars`
+2. The role will build and deploy a custom image
+
+### Extras
+
+- **RCON**: Enabled by default on port 25575. Allows remote console admin.
+- **Whitelist**: Set `minecraft.whitelist_enabled: true` to require whitelist
+- **Command Blocks**: Set `minecraft.enable_command_block: true` to enable