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)

# 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:

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