PXC-5141 - [DOCS] - [feedback] It doesn't work with podman compose 8.4

	modified:   docs/docker-compose.md

Author: patrickbirch

docs/docker-compose.md

@@ -10,6 +10,58 @@ We gather [Telemetry data](telemetry.md) in the Percona packages and Docker imag
 
 This guide shows you how to deploy a three-node Percona XtraDB Cluster 8.4 using Docker Compose. You generate SSL certificates on the first node and copy them to the other two nodes to enable secure communication.
 
+## Using Podman instead of Docker
+
+Podman can be used as an alternative to Docker because it supports the same container images. However, it is not fully compatible with Docker Compose.
+
+To run this deployment with Podman, you may need to use tools such as podman compose, podman-compose, or a configured Docker Compose compatibility layer, depending on your environment.
+
+Podman uses a different architecture (for example, pods and rootless containers), so networking, volume mounts, and service behavior may differ from Docker Compose.
+
+This deployment is designed and tested with Docker Compose. Podman support is not guaranteed. If you use Podman, verify that the cluster operates correctly before using it beyond testing or experimentation.
+
+You can use the same Compose file and workflow with [Podman](https://podman.io/). Use Podman 4.1 or later; the built-in `podman compose` subcommand requires 4.1 or newer. With older Podman, use the separate podman-compose tool. Then:
+
+* Prerequisites: Podman and Podman Compose (for example, `pip install podman-compose` or your distro’s package) if you are not using built-in `podman compose`. For rootless Podman, ensure the user has enough resources (for example, `sysctl user.max_user_namespaces` and subuid/subgid ranges).
+
+* Commands: Replace `docker compose` with `podman compose` or `podman-compose`, and `docker exec` with `podman exec`. Examples:
+
+  * Start node 1: `podman compose up -d pxc1` (or `podman-compose up -d pxc1`)
+
+  * Start other nodes: `podman compose up -d pxc2 pxc3`
+
+  * Validate: `podman exec -it pxc1 mysql -uroot -p${MYSQL_ROOT_PASSWORD} -e "SHOW STATUS LIKE 'wsrep_cluster_size';"`
+
+* Directory structure: The same layout (`pxc-cluster/` with `certs/`, `conf.d/`, and `init/`) works with Podman. Run `podman compose` from the project directory (for example, `pxc-cluster/`) so the relative volume paths in the Compose file resolve correctly.
+
+* Compose file: The `docker-compose.yml` in this guide works as-is with Podman; the `bridge` network and volume mounts are supported. For rootless Podman, see the volume mount options below.
+
+### Handling rootless permissions (most important for Podman)
+
+In Docker, the daemon runs as root and can override file permissions. In Podman, if you run as a normal user, the MySQL process inside the container (usually UID 1001 or 999) may not have permission to read the files you created on the host. Ensure the files are readable by the container. On systems with SELinux, use the `:Z` (private) or `:z` (shared) mount option so Podman relabels the volume for the container. In your `docker-compose.yml`, use:
+
+```text
+volumes:
+  - ./certs:/etc/mysql/certs:ro,Z
+  - ./conf.d:/etc/percona-xtradb-cluster.conf.d:ro,Z
+```
+
+Apply the same volume options to every service (pxc1, pxc2, pxc3). Without `:Z` or `:z`, the container may fail to read certs or config when running rootless on SELinux.
+
+### podman-compose vs docker-compose
+
+* If you use podman-compose (the Python tool): It reads the directory structure and `.env` file the same way Docker does.
+
+* If you use docker-compose with the Podman socket: This is often more stable for PXC. Set `DOCKER_HOST` to point at the Podman socket (for example, `unix:///run/user/$(id -u)/podman/podman.sock`) so `docker compose` talks to Podman.
+
+### Network considerations
+
+PXC uses specific ports for cluster communication (4567, 4568, 4444). Podman uses different networking (netavark or CNI). If nodes cannot find each other:
+
+* Keep using a named network in the Compose file (for example, `pxcnet`) so Podman can resolve container names (pxc1, pxc2, pxc3).
+
+* If problems persist, try setting `network_mode: slirp4netns` on the services, or run the stack rootful to use the default bridge.
+
 The following procedure describes setting up a simple 3-node cluster
 for evaluation and testing purposes. Do not use these instructions in a
 production environment because the MySQL certificates generated in this
@@ -19,7 +71,7 @@ In a production environment, you should generate and store the certificates to b
 
 ## Prerequisites
 
-* Docker and Docker Compose installed
+* Docker and Docker Compose installed (or Podman 4.1 or later and Podman Compose; see [Using Podman instead of Docker](#using-podman-instead-of-docker))
 
 * At least 3 GB of memory per container
 
@@ -207,23 +259,25 @@ This structure helps manage configuration files, TLS/SSL certificates, and setup
     ```shell
     docker compose up -d pxc1
     ```
+    (With Podman: `podman compose up -d pxc1` or `podman-compose up -d pxc1`.)
 
     Then, start the remaining nodes:
 
     
     ```shell
     docker compose up -d pxc2 pxc3
     ```
+    (With Podman: `podman compose up -d pxc2 pxc3` or `podman-compose up -d pxc2 pxc3`.)
 
 7. Validate the Cluster
 
-    Check the status of each node:
+    Check the status of each node. Exact commands (run from the host; use the same password as in your `.env`):
 
-    
     ```shell
     docker exec -it pxc1 mysql -uroot -p${MYSQL_ROOT_PASSWORD} -e "SHOW STATUS LIKE 'wsrep_cluster_size';"
     docker exec -it pxc2 mysql -uroot -p${MYSQL_ROOT_PASSWORD} -e "SHOW STATUS LIKE 'wsrep_cluster_status';"
     ```
+    (With Podman: use `podman exec` instead of `docker exec`.)
 
 You should see all three nodes joined and synchronized.