external-minecraft/README.md

# 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