From 3715b6b44a3ce155dfa3484d808085f5e36fcb99 Mon Sep 17 00:00:00 2001 From: Jordan Del Pilar Date: Wed, 15 Jul 2026 09:02:45 -0700 Subject: [PATCH 1/8] update(inventory): added new minecraft_servers group added new `minecraft_servers` group. This groups host that will host minecraft servers Added `new-bark` to the new group. --- inventory.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/inventory.yaml b/inventory.yaml index 4c4b6a8..cf8dd9a 100644 --- a/inventory.yaml +++ b/inventory.yaml @@ -29,3 +29,6 @@ all: gitea_servers: hosts: new-bark: + minecraft_servers: + hosts: + new-bark: -- 2.54.0 From f4535e8d9f4cb0a8e4204157a16bce70290af9ad Mon Sep 17 00:00:00 2001 From: Jordan Del Pilar Date: Wed, 15 Jul 2026 09:05:21 -0700 Subject: [PATCH 2/8] update(new-bark): added new variables for minecraft_server role added new required and optional variables for the new `minecraft_server` role in host_vars for `new-bark` --- host_vars/new-bark.yaml | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/host_vars/new-bark.yaml b/host_vars/new-bark.yaml index 6a1437b..9658bc2 100644 --- a/host_vars/new-bark.yaml +++ b/host_vars/new-bark.yaml @@ -12,6 +12,8 @@ ansible_become_password: !vault | podman_config_base_dir: /appdata/podman podman_quadlet_base_dir: "/home/{{ ansible_user }}/.config/containers/systemd" +timezone: America/Los_Angeles + dns_services: - name: adguard image: docker.io/adguard/adguardhome:latest @@ -237,3 +239,14 @@ backup_paths: - /storage/public-assets keep_daily: 7 keep_weekly: 4 + +minecraft_servers: + - name: vanilla + image: docker.io/itzg/minecraft-server:latest + port: 25565 + env: + MEMORY: 4G + USE_AIKAR_FLAGS: "true" + TYPE: PAPER + ENABLE_AUTOPAUSE: "true" + OPS: redjordan1 -- 2.54.0 From c862887c4ec83e4010fa209d174a192c1dafe969 Mon Sep 17 00:00:00 2001 From: Jordan Del Pilar Date: Wed, 15 Jul 2026 09:27:05 -0700 Subject: [PATCH 3/8] feat(minecraft): add defaults file created `defaults/main.yaml` to store defaults for this role. these defaults are the lowest precedence so will be over written at any level as needed --- roles/minecraft_server/defaults/main.yaml | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 roles/minecraft_server/defaults/main.yaml diff --git a/roles/minecraft_server/defaults/main.yaml b/roles/minecraft_server/defaults/main.yaml new file mode 100644 index 0000000..b85627d --- /dev/null +++ b/roles/minecraft_server/defaults/main.yaml @@ -0,0 +1,4 @@ +--- +container_owner: jdelpilar +mc_port: 25565 +timezone: America/Los_Angeles -- 2.54.0 From f8770f2da469e197f6777dc67a5d24f13e314d02 Mon Sep 17 00:00:00 2001 From: Jordan Del Pilar Date: Wed, 15 Jul 2026 11:10:59 -0700 Subject: [PATCH 4/8] feat(minecraft): added handlers Added new handler file. This handles reloading systemd and starting new minecraft server containers --- roles/minecraft_server/handlers/main.yaml | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 roles/minecraft_server/handlers/main.yaml diff --git a/roles/minecraft_server/handlers/main.yaml b/roles/minecraft_server/handlers/main.yaml new file mode 100644 index 0000000..3e6861b --- /dev/null +++ b/roles/minecraft_server/handlers/main.yaml @@ -0,0 +1,7 @@ +- name: Restart changed Minecraft Services + ansible.builtin.systemd: + name: "mc-{{ item.item.name }}" + state: restarted + scope: user + daemon_reload: true + loop: "{{ minecraft_quadlet_results.results | selectattr('changed', 'equalto', true) | list }}" -- 2.54.0 From 01219e53b82be7a2f87a47cacdad85be4b270b41 Mon Sep 17 00:00:00 2001 From: Jordan Del Pilar Date: Wed, 15 Jul 2026 11:11:22 -0700 Subject: [PATCH 5/8] feat(minecraft): add new minecraft container template --- .../templates/minecraft.container.j2 | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 roles/minecraft_server/templates/minecraft.container.j2 diff --git a/roles/minecraft_server/templates/minecraft.container.j2 b/roles/minecraft_server/templates/minecraft.container.j2 new file mode 100644 index 0000000..3773416 --- /dev/null +++ b/roles/minecraft_server/templates/minecraft.container.j2 @@ -0,0 +1,40 @@ +# {{ ansible_managed }} +[Unit] +After=network-online.target + +StartLimitBurst=10 +StartLimitIntervalSec=120 + +[Container] +ContainerName=mc-{{ item.name }} +Image={{ item.image }} + +Network=management-net +PublishPort={{ item.port | default(mc_port) }}:25565 + +AutoUpdate=registry + +Label=category=management +Label=owner={{ item.container_owner | default('jdelpilar') }} + +Volume={{ podman_config_base_dir }}/mc-{{ item.name }}/data:/data +{% if item.volumes is defined %} +{% for volume in item.volumes %} +Volume={{ volume }} +{% endfor %} +{% endif %} + +Environment=TZ={{ timezone | default('America/Los_Angeles') }} +Environment=EULA=true +{% if item.env is defined %} +{% for key, value in item.env.items() | sort %} +Environment={{ key }}={{ value }} +{% endfor %} +{% endif %} + +[Service] +Restart=on-failure +RestartSec=5 + +[Install] +WantedBy=default.target -- 2.54.0 From 3f85270020fd4f5d52eaa5ee31fb1ab732c0a1f4 Mon Sep 17 00:00:00 2001 From: Jordan Del Pilar Date: Wed, 15 Jul 2026 11:13:28 -0700 Subject: [PATCH 6/8] feat(minecraft): add new minecraft server tasks added new core tasks for the minecraft_server role. this role does the following - create new minecraft podman config directory - create minecraft container file - start all minecraft servers. --- roles/minecraft_server/tasks/main.yaml | 27 ++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 roles/minecraft_server/tasks/main.yaml diff --git a/roles/minecraft_server/tasks/main.yaml b/roles/minecraft_server/tasks/main.yaml new file mode 100644 index 0000000..afc3f78 --- /dev/null +++ b/roles/minecraft_server/tasks/main.yaml @@ -0,0 +1,27 @@ +--- +- name: Create Minecraft Directories + ansible.builtin.file: + path: "{{ podman_config_base_dir }}/mc-{{ item.name }}/data" + state: directory + mode: "0755" + loop: "{{ minecraft_servers }}" + +- name: Create Minecraft Quadlets + ansible.builtin.template: + src: minecraft.container.j2 + dest: "{{ podman_quadlet_base_dir }}/services/mc-{{ item.name }}.container" + owner: "{{ ansible_user }}" + mode: "644" + loop: "{{ minecraft_servers }}" + register: minecraft_quadlet_results + notify: Restart changed Minecraft Services + +- name: Flush Handlers + ansible.builtin.meta: flush_handlers + +- name: Start Minecraft Servers + ansible.builtin.systemd: + name: "mc-{{ item.name }}" + state: started + scope: user + loop: "{{ minecraft_servers }}" -- 2.54.0 From 037d825eac668367104d08a6568a479518800fe8 Mon Sep 17 00:00:00 2001 From: Jordan Del Pilar Date: Wed, 15 Jul 2026 11:13:49 -0700 Subject: [PATCH 7/8] docs(minecraft): added minecraft role `README.md` --- roles/minecraft_server/README.md | 59 ++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 roles/minecraft_server/README.md diff --git a/roles/minecraft_server/README.md b/roles/minecraft_server/README.md new file mode 100644 index 0000000..e550001 --- /dev/null +++ b/roles/minecraft_server/README.md @@ -0,0 +1,59 @@ +# Role: Minecraft Server +Sets up and deploys minecraft server container + +## Tags +- minecraft + +## Required Variables +Below is an annotated breakdown of the required variables and their structure for this role + +These blocks should be defined in the `host_vars` file for any host that should be a minecraft server + +> [!WARNING] +> Any variable marked `# !SENSITIVE` **should not** be stored in plain text under any circumstance + +### Minecraft Info +Defines settings for the Minecraft server container settings + +```yaml +# (required) List of all minecraft server containers to be deployed +# you can run as many minecraft servers as the hardware can handle. However, all will need a unique port +# at least one service is required +minecraft_servers: + # (required) name of the server container + # all containers and services will be prefixed with 'mc-' + # for example if you list 'vanilla' as the name the resulting container/service name will be 'mc-vanilla' + # format: snake_case + - name: + # (required) URL of container image + # can be from any container registry + # recommended image is: docker.io/itzg/minecraft-server:latest + # format: url + image: docker.io/itzg/minecraft-server:latest + # (optional) host port to bind to the container + # this must be unique for each server instance + # default: 25565 + # format: int + port: + # (optional) list of environment variables to pass to the container + # these are primarily used to define settings for the minecraft server + # for more info please read the docs for your specific container image + # memory setting example listed to show proper format + # format: key value pair + env: + MEMORY: 4G +``` + +## Templates + +### minecraft.container.j2 +This template is used to generate .container files for Minecraft servers. This template is heavily opinionated to be a minecraft server instance and should not be used a generic template for quadlets. + +## Execution +> [!NOTE] +> If this role makes changes to the quadlet file on the host the server will be restarted. If you are hosting this server for multiple users please keep that in mind + +To run this command without running all roles in the playbook, use the following command +```bash +ansible-playbook site.yaml --tags "minecraft" +``` -- 2.54.0 From 2c307f15f55751bd340d2bf0a2e453e5f8f24dbe Mon Sep 17 00:00:00 2001 From: Jordan Del Pilar Date: Wed, 15 Jul 2026 11:14:48 -0700 Subject: [PATCH 8/8] feat(site.yaml): added new minecraft role to site.yaml added new minecraft_server role to `site.yaml` along with tags to run role independently --- site.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/site.yaml b/site.yaml index 9eea2a0..6e15623 100644 --- a/site.yaml +++ b/site.yaml @@ -29,3 +29,10 @@ tags: - common - backup + +- name: Minecraft Setup + hosts: minecraft_servers + roles: + - minecraft_server + tags: + - minecraft -- 2.54.0