Switch quickstart to docker compose v2

We want to use podman to run our containers, but the podman-compose
tool has been problematic to use in OpenDev and has also caused
some confusion for users.  It also seems the podman project is
favoring declaring systems using k8s syntax rather than compose,
which is putting the podman-compose tool future in question.

This change updates the quickstart to use "docker compose" (ie,
docker-compose v2) instead of podman-compose.

Because we want to continue using speculative container testing
which does not work for quay.io images when using docker, we will
use the podman backend with docker compose.  This is what we
are moving toward in OpenDev.  We hope that it is the best of both
worlds.

Users likely don't need such a complex setup, so we will adjust
the documentation to use "docker compose" but not mention anything
about podman.  That will remain a test implementation detail,
at least as long as we think they are sufficiently compatible that
we can get away with testing something slightly different than
our instructions.

This switches to packaged git-review for simplicity because
pip install does not work in noble.

Fedora and OpenSuse installation instructions are similarly updated.

Red Hat / CentOS instructions are removed because this author does
not have a way to verify package names.  Their return by someone
knowledgable with that is welcome.

Change-Id: I238f6db178af86fa7203203993c90bd8d1371712
Depends-On: https://review.opendev.org/923083
Depends-On: https://review.opendev.org/925916
Co-Authored-By: Clark Boylan <clark.boylan@gmail.com>

doc/source/tutorials/keycloak.rst

@@ -46,16 +46,16 @@ that we can update Zuul's configuration to add authentication.
 .. code-block:: shell
 
    cd zuul/doc/source/examples
-   podman-compose -p zuul-tutorial stop
+   docker compose -p zuul-tutorial stop
 
 Restart the containers with a new Zuul configuration.
 
 .. code-block:: shell
 
    cd zuul/doc/source/examples
-   ZUUL_TUTORIAL_CONFIG="./keycloak/etc_zuul/" podman-compose -p zuul-tutorial up -d
+   ZUUL_TUTORIAL_CONFIG="./keycloak/etc_zuul/" docker compose -p zuul-tutorial up -d
 
-This tells podman-compose to use these Zuul `config files
+This tells docker compose to use these Zuul `config files
 <https://opendev.org/zuul/zuul/src/branch/master/doc/source/examples/keycloak>`_.
 
 Start Keycloak
@@ -67,7 +67,7 @@ with this command:
 .. code-block:: shell
 
    cd zuul/doc/source/examples/keycloak
-   podman-compose -p zuul-tutorial-keycloak up -d
+   docker compose -p zuul-tutorial-keycloak up -d
 
 Once Keycloak is running, you can visit the web interface at
 http://localhost:8082/

doc/source/tutorials/quick-start.rst

@@ -31,26 +31,18 @@ Before you start, ensure that some needed packages are installed.
 
 .. code-block:: shell
 
-   # Red Hat / CentOS:
-
-   sudo yum install podman git python3
-   sudo python3 -m pip install git-review podman-compose
-
    # Fedora:
 
-   sudo dnf install podman git python3
-   sudo python3 -m pip install git-review podman-compose
+   sudo dnf install git git-review docker-compose
 
    # OpenSuse:
 
-   sudo zypper install podman git python3
-   sudo python3 -m pip install git-review podman-compose
+   sudo zypper install git git-review docker-compose
 
    # Ubuntu (Noble or later) / Debian:
 
-   sudo apt-get update
-   sudo apt-get install podman git python3-pip
-   sudo python3 -m pip install git-review podman-compose
+   sudo apt update
+   sudo apt install git git-review docker-compose-v2
 
 
 Clone the Zuul repository:
@@ -60,22 +52,22 @@ Clone the Zuul repository:
    git clone https://opendev.org/zuul/zuul
 
 Then cd into the directory containing this document, and run
-podman-compose in order to start Zuul, Nodepool and Gerrit.
+docker compose in order to start Zuul, Nodepool and Gerrit.
 
 .. code-block:: shell
 
    cd zuul/doc/source/examples
-   podman-compose -p zuul-tutorial up
+   docker compose -p zuul-tutorial up
 
 For reference, the files in that directory are also `browsable on the web
 <https://opendev.org/zuul/zuul/src/branch/master/doc/source/examples>`_.
 
 All of the services will be started with debug-level logging sent to
-the standard output of the terminal where podman-compose is running.
+the standard output of the terminal where docker compose is running.
 You will see a considerable amount of information scroll by, including
 some errors.  Zuul will immediately attempt to connect to Gerrit and
 begin processing, even before Gerrit has fully initialized.  The
-podman composition includes scripts to configure Gerrit and create an
+docker composition includes scripts to configure Gerrit and create an
 account for Zuul.  Once this has all completed, the system should
 automatically connect, stabilize and become idle.  When this is
 complete, you will have the following services running:

doc/source/tutorials/tracing.rst

@@ -26,16 +26,16 @@ that we can update Zuul's configuration to enable tracing.
 .. code-block:: shell
 
    cd zuul/doc/source/examples
-   podman-compose -p zuul-tutorial stop
+   docker compose -p zuul-tutorial stop
 
 Restart the containers with a new Zuul configuration.
 
 .. code-block:: shell
 
    cd zuul/doc/source/examples
-   ZUUL_TUTORIAL_CONFIG="./tracing/etc_zuul/" podman-compose -p zuul-tutorial up -d
+   ZUUL_TUTORIAL_CONFIG="./tracing/etc_zuul/" docker compose -p zuul-tutorial up -d
 
-This tells podman-compose to use these Zuul `config files
+This tells docker compose to use these Zuul `config files
 <https://opendev.org/zuul/zuul/src/branch/master/doc/source/examples/tracing>`_.
 The only change compared to the quick-start is to add a
 :attr:`tracing` section to ``zuul.conf``:
@@ -59,7 +59,7 @@ with this command:
 .. code-block:: shell
 
    cd zuul/doc/source/examples/tracing
-   podman-compose -p zuul-tutorial-tracing up -d
+   docker compose -p zuul-tutorial-tracing up -d
 
 You can visit http://localhost:16686/search to verify it is running.
 

playbooks/tutorial/admin.yaml

@@ -1,45 +1,55 @@
 # Stop the basic tutorial
-- name: Run podman-compose down
+- name: Run docker compose down
   when: not local
   shell:
-    cmd: podman-compose -p zuul-tutorial stop
+    cmd: docker compose -p zuul-tutorial stop
     chdir: src/opendev.org/zuul/zuul/doc/source/examples
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
-- name: Run podman-compose down
+- name: Run docker compose down
   when: local
   shell:
-    cmd: podman-compose -p zuul-tutorial stop
+    cmd: docker compose -p zuul-tutorial stop
     chdir: ../../doc/source/examples
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
 # Restart with the new config
-- name: Run podman-compose up
+- name: Run docker compose up
   when: not local
   shell:
-    cmd: podman-compose -p zuul-tutorial up -d
+    cmd: docker compose -p zuul-tutorial up -d
     chdir: src/opendev.org/zuul/zuul/doc/source/examples
   environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
     ZUUL_TUTORIAL_CONFIG: "./keycloak/etc_zuul/"
 
-- name: Run podman-compose up
+- name: Run docker compose up
   when: local
   shell:
-    cmd: podman-compose -p zuul-tutorial up -d
+    cmd: docker compose -p zuul-tutorial up -d
     chdir: ../../doc/source/examples
   environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
     ZUUL_TUTORIAL_CONFIG: "./keycloak/etc_zuul/"
 
 # Start keycloak
-- name: Run podman-compose up
+- name: Run docker compose up
   when: not local
   shell:
-    cmd: podman-compose -p zuul-tutorial-keycloak up -d
+    cmd: docker compose -p zuul-tutorial-keycloak up -d
     chdir: src/opendev.org/zuul/zuul/doc/source/examples/keycloak
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
-- name: Run podman-compose up
+- name: Run docker compose up
   when: local
   shell:
-    cmd: podman-compose -p zuul-tutorial-keycloak up -d
+    cmd: docker compose -p zuul-tutorial-keycloak up -d
     chdir: ../../doc/source/examples/keycloak
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
 # In case ZK is shutdown first, allow the locks to expire.
 - name: Delay for ZK lock expiration

playbooks/tutorial/post.yaml

@@ -5,22 +5,24 @@
         state: directory
         path: "{{ ansible_user_dir }}/logs"
         mode: 0755
-    - name: Save podman log files
+    - name: Save container log files
       shell: |
         set +e
-        podman logs zuul-tutorial_gerrit_1 > {{ ansible_user_dir }}/logs/gerrit.log 2>&1
-        podman logs zuul-tutorial_gerritconfig_1 > {{ ansible_user_dir }}/logs/gerritconfig.log 2>&1
-        podman logs zuul-tutorial_zk_1 > {{ ansible_user_dir }}/logs/zk.log 2>&1
-        podman logs zuul-tutorial_mysql_1 > {{ ansible_user_dir }}/logs/mysql.log 2>&1
-        podman logs zuul-tutorial_scheduler_1 > {{ ansible_user_dir }}/logs/scheduler.log 2>&1
-        podman logs zuul-tutorial_web_1 > {{ ansible_user_dir }}/logs/web.log 2>&1
-        podman logs zuul-tutorial_executor_1 > {{ ansible_user_dir }}/logs/executor.log 2>&1
-        podman logs zuul-tutorial_node_1 > {{ ansible_user_dir }}/logs/node.log 2>&1
-        podman logs zuul-tutorial_launcher_1 > {{ ansible_user_dir }}/logs/launcher.log 2>&1
-        podman logs zuul-tutorial_logs_1 > {{ ansible_user_dir }}/logs/logs.log 2>&1
-        podman logs zuul-tutorial-tracing_jaeger_1 > {{ ansible_user_dir }}/logs/jaeger.log 2>&1
+        docker logs zuul-tutorial-gerrit-1 > {{ ansible_user_dir }}/logs/gerrit.log 2>&1
+        docker logs zuul-tutorial-gerritconfig-1 > {{ ansible_user_dir }}/logs/gerritconfig.log 2>&1
+        docker logs zuul-tutorial-zk-1 > {{ ansible_user_dir }}/logs/zk.log 2>&1
+        docker logs zuul-tutorial-mysql-1 > {{ ansible_user_dir }}/logs/mysql.log 2>&1
+        docker logs zuul-tutorial-scheduler-1 > {{ ansible_user_dir }}/logs/scheduler.log 2>&1
+        docker logs zuul-tutorial-web-1 > {{ ansible_user_dir }}/logs/web.log 2>&1
+        docker logs zuul-tutorial-executor-1 > {{ ansible_user_dir }}/logs/executor.log 2>&1
+        docker logs zuul-tutorial-node-1 > {{ ansible_user_dir }}/logs/node.log 2>&1
+        docker logs zuul-tutorial-launcher-1 > {{ ansible_user_dir }}/logs/launcher.log 2>&1
+        docker logs zuul-tutorial-logs-1 > {{ ansible_user_dir }}/logs/logs.log 2>&1
+        docker logs zuul-tutorial-tracing_jaeger-1 > {{ ansible_user_dir }}/logs/jaeger.log 2>&1
         exit 0
-    - name: Copy podman log files to executor
+      environment:
+        DOCKER_HOST: unix:///run/podman/podman.sock
+    - name: Copy container log files to executor
       synchronize:
         mode: pull
         src: "{{ ansible_user_dir }}/logs/"

playbooks/tutorial/pre.yaml

@@ -1,5 +1,30 @@
 - hosts: all
   roles:
     - ensure-pip
-    - ensure-podman
+    - ensure-docker
+    - role: ensure-podman
+      ensure_podman_socket: true
     - use-buildset-registry
+  tasks:
+    # docker-compose-v2 depends on the docker service. Disable it to
+    # ensure we're not accidentally using the docker daemon.
+    - name: Disable docker daemon service
+      become: true
+      service:
+        name: docker
+        state: stopped
+        enabled: false
+    - name: Disable docker socket service
+      become: true
+      service:
+        name: docker.socket
+        state: stopped
+        enabled: false
+    - name: Start buildx builder
+      # This may not be necessary under a normal docker install
+      # https://github.com/docker/buildx/issues/344
+      shell: |
+        echo "FROM scratch" | docker buildx build - || true
+      environment:
+        DOCKER_HOST: unix:///run/podman/podman.sock
+      become: true

playbooks/tutorial/roles/setup-tutorial/tasks/main.yaml

@@ -30,17 +30,21 @@
         ssh_agent: "{{ ssh_agent_new }}"
   when: ssh_public_key is not defined or ssh_public_key == ''
 
-- name: Run podman-compose up
+- name: Run docker compose up
   when: not local
   shell:
-    cmd: podman-compose -p zuul-tutorial up -d
+    cmd: docker compose -p zuul-tutorial up -d
     chdir: src/opendev.org/zuul/zuul/doc/source/examples
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
-- name: Run podman-compose up
+- name: Run docker compose up
   when: local
   shell:
-    cmd: podman-compose -p zuul-tutorial up -d
+    cmd: docker compose -p zuul-tutorial up -d
     chdir: ../../doc/source/examples
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
 - name: Print list of images
   command: podman image ls --all --digests --no-trunc

playbooks/tutorial/run-tutorial.yaml

@@ -3,7 +3,8 @@
       package:
         name:
           - git-review
-          - podman-compose
+          # This should only be needed with the podman backend
+          - catatonit
         state: present
       become: true
   when: not local

playbooks/tutorial/tracing.yaml

@@ -1,45 +1,55 @@
 # Stop the basic tutorial
-- name: Run podman-compose down
+- name: Run docker compose down
   when: not local
   shell:
-    cmd: podman-compose -p zuul-tutorial stop
+    cmd: docker compose -p zuul-tutorial stop
     chdir: src/opendev.org/zuul/zuul/doc/source/examples
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
-- name: Run podman-compose down
+- name: Run docker compose down
   when: local
   shell:
-    cmd: podman-compose -p zuul-tutorial stop
+    cmd: docker compose -p zuul-tutorial stop
     chdir: ../../doc/source/examples
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
 # Restart with the new config
-- name: Run podman-compose up
+- name: Run docker compose up
   when: not local
   shell:
-    cmd: podman-compose -p zuul-tutorial up -d
+    cmd: docker compose -p zuul-tutorial up -d
     chdir: src/opendev.org/zuul/zuul/doc/source/examples
   environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
     ZUUL_TUTORIAL_CONFIG: "./tracing/etc_zuul/"
 
-- name: Run podman-compose up
+- name: Run docker compose up
   when: local
   shell:
-    cmd: podman-compose -p zuul-tutorial up -d
+    cmd: docker compose -p zuul-tutorial up -d
     chdir: ../../doc/source/examples
   environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
     ZUUL_TUTORIAL_CONFIG: "./tracing/etc_zuul/"
 
 # Start Jaeger
-- name: Run podman-compose up
+- name: Run docker compose up
   when: not local
   shell:
-    cmd: podman-compose -p zuul-tutorial-tracing up -d
+    cmd: docker compose -p zuul-tutorial-tracing up -d
     chdir: src/opendev.org/zuul/zuul/doc/source/examples/tracing
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
-- name: Run podman-compose up
+- name: Run docker compose up
   when: local
   shell:
-    cmd: podman-compose -p zuul-tutorial-tracing up -d
+    cmd: docker compose -p zuul-tutorial-tracing up -d
     chdir: ../../doc/source/examples/tracing
+  environment:
+    DOCKER_HOST: unix:///run/podman/podman.sock
 
 # In case ZK is shutdown first, allow the locks to expire.
 - name: Delay for ZK lock expiration