examples: podman quadlet example (#4099)

Author: lethedata

examples/podman-quadlets/README.md

@@ -0,0 +1,45 @@
+# Podman Quadlet Example
+
+This example demonstrates how to deploy multiple autoscaling minecraft servers behind mc-router with [podman quadlets](https://docs.podman.io/en/stable/markdown/podman-systemd.unit.5.html).
+
+The commands listed below assume rootless podman but can easily be modified for rootful.
+
+## mc-router.host label
+
+In `mc@.container`, replace `example.com` with your domain.
+
+## Server instance configuration
+
+Each server instance requries an environment file with a matching name in the mc folder; e.g. instance `example` uses `mc/example.env`.[^1]
+
+## Container auto-removal fix
+
+Once the quadlets files are installed and daemon-reloaded, the generated service file needs to be edited due to generated quadlets always adding `--rm`.[^2]
+To fix this, run `systemctl --user edit mc@.service` and replace the `ExecStart` entry with a copy that substitues `--restart=unless-stopped` where `--rm` is.
+The  drop-in should look something like this:
+
+```ini
+[Service]
+ExecStart=
+ExecStart=/usr/bin/podman run --name %p-%i --replace --restart=unless-stopped ...
+```
+
+## Start containers/services
+
+```sh
+systemctl --user enable --now podman.socket
+systemctl --user start mc@example.service mc-router.service
+# instances are enabled by symlinking from the template
+ln -s ${XDG_CONFIG_HOME}/containers/systemd/mc@.service ${XDG_CONFIG_HOME}/containers/systemd/mc@example.service
+```
+
+## Rootless notes
+
+If running rootless, be sure to enable lingering with `sudo loginctl enable-linger $USER`.
+
+Also note that source IPs are currently lost due to how rootless podman handles custom networks.
+This should be fixed in a future podman release.[^3]
+
+[^1]: The base config is a [template file](https://docs.podman.io/en/stable/markdown/podman-systemd.unit.5.html#template-files) with instance names after the @ sign .
+[^2]: <https://github.com/podman-container-tools/podman/discussions/28837>
+[^3]: <https://github.com/podman-container-tools/podman/pull/28478>

examples/podman-quadlets/mc-router.container

@@ -0,0 +1,24 @@
+[Unit]
+Description=Minecraft proxy with autoscaling support
+
+[Container]
+Image=docker.io/itzg/mc-router
+ContainerName=%N
+AutoUpdate=registry
+UserNS=host
+Volume=%t/podman/podman.sock:/var/run/docker.sock:ro
+Network=minecraft.network
+PublishPort=25565:25565
+SecurityLabelDisable=true
+Environment=\
+	"IN_DOCKER=true" \
+	"AUTO_SCALE_DOWN=true" \
+	"AUTO_SCALE_UP=true" \
+	"AUTO_SCALE_DOWN_AFTER=10m" \
+	"AUTO_SCALE_ASLEEP_MOTD='Server is asleep. Join again to wake it up!'"
+
+[Service]
+Restart=always
+
+[Install]
+WantedBy=default.target

examples/podman-quadlets/mc/example.env

@@ -0,0 +1,9 @@
+# General options
+INIT_MEMORY=1G
+MAX_MEMORY=4G
+
+# Server options
+EULA=TRUE
+VIEW_DISTANCE=16
+DIFFICULTY=normal
+MOTD=Example Server!\nRunning version %VERSION%

examples/podman-quadlets/mc@.container

@@ -0,0 +1,26 @@
+[Unit]
+Description=Minecraft server instance
+Before=mc-router.service
+
+[Container]
+Image=docker.io/itzg/minecraft-server
+ContainerName=%p-%i
+AutoUpdate=registry
+UserNS=auto
+Volume=%p-%i:/data:Z,U
+Network=minecraft.network
+PodmanArgs=--tty --interactive
+HealthCmd="/usr/local/bin/mc-health"
+HealthInterval=10s
+HealthRetries=20
+HealthStartPeriod=1m
+HealthTimeout=10s
+Label=mc-router.host=%p-%i.example.com
+EnvironmentFile=./mc/%i.env
+
+[Service]
+Restart=on-abnormal
+RemainAfterExit=yes
+
+[Install]
+WantedBy=default.target

examples/podman-quadlets/minecraft.network

@@ -0,0 +1,2 @@
+[Network]
+Driver=bridge