┌─────────────────────────────────────────────────┐
│              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)

# 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

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

# 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

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:

make restore

Uninstall

make uninstall   # Interactive confirmation

Or manually:

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:

Set minecraft.use_custom_container: true in group_vars
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