test(e2e): rewrite Linux matrix runner with testcontainers-go

.github/workflows/e2e.yml

@@ -24,7 +24,10 @@ jobs:
     timeout-minutes: 60
     steps:
       - uses: actions/checkout@v7
-      - run: bash tests/e2e/linux/e2e.sh
+      # No host Go anywhere: the suite runs from the Compose runner service
+      # driving the runner daemon through the mounted socket (same invocation
+      # as docs/e2e.md), so CI dogfoods the documented setup.
+      - run: docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
 
   e2e-windows:
     if: github.repository == 'version-fox/vfox-flutter'

docs/e2e.md

@@ -6,15 +6,29 @@ each `vfox` x `flavor` x `mirror` combination gets its own throwaway container.
 
 ## Ubuntu 26.04.1
 
-Assume that Docker Engine (in either rootful or rootless mode) is already installed.
-
-Execute in Bash,
+Only Docker Engine (in either rootful or rootless mode) is required on the
+host. Execute in Bash,
 
 ```bash
 sudo apt install --assume-yes git
 git clone git@github.com:version-fox/vfox-flutter.git
 cd ./vfox-flutter/
-bash tests/e2e/linux/e2e.sh
+docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
+```
+
+With rootless Docker the daemon socket lives elsewhere; point `DOCKER_SOCK`
+at it instead:
+
+```bash
+DOCKER_SOCK="$XDG_RUNTIME_DIR/docker.sock" \
+    docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
+```
+
+To check the `vfox` x `flavor` x `mirror` matrix expansion without
+starting containers, override the service command:
+
+```bash
+docker compose -f tests/e2e/linux/compose.yaml run --rm e2e go test -short ./...
 ```
 
 On ARM64 it runs the official flavor only: OpenHarmony publishes no `linux-arm64` Dart SDK (see `docs/ohos.md`), so the
@@ -28,7 +42,8 @@ override the architecture:
 
 ```bash
 docker run --privileged --rm tonistiigi/binfmt --install all
-ARCH=arm64 bash tests/e2e/linux/e2e.sh
+cd ./vfox-flutter/
+ARCH=arm64 docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
 ```
 
 ## Windows 11 Pro

tests/e2e/linux/Dockerfile

@@ -2,21 +2,23 @@ FROM ubuntu:26.04
 
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN <<EOF
-set -o errexit -o nounset -o xtrace
-apt-get update
-apt-get install --assume-yes \
-    curl \
-    git \
-    golang \
-    jq \
-    zip
-EOF
+# NOTE: no heredoc here. This Dockerfile is built through the daemon's
+# classic `POST /build` endpoint via testcontainers-go
+# (tests/e2e/linux/e2e_test.go), which does not understand `RUN <<EOF`
+# heredocs and silently drops their body. The chained-`;` form below works
+# on both the classic builder and BuildKit (`docker build`).
+RUN set -o errexit -o nounset -o xtrace; \
+    apt-get update; \
+    apt-get install --assume-yes \
+        curl \
+        git \
+        golang \
+        zip
 
 COPY metadata.lua /e2e/metadata.lua
 COPY hooks /e2e/hooks
 COPY lib /e2e/lib
-COPY tests/e2e/linux /e2e/tests/e2e/linux
 
-ENTRYPOINT ["bash"]
-CMD ["/e2e/tests/e2e/linux/run.sh"]
+# Long-lived container: the Go test (e2e_test.go) drives every phase through
+# exec calls, so the main process just idles here.
+CMD ["sleep", "infinity"]

tests/e2e/linux/compose.yaml

@@ -0,0 +1,44 @@
+# Host-side runner for the Linux container E2E suite (see docs/e2e.md).
+#
+#   docker compose -f tests/e2e/linux/compose.yaml run --rm e2e
+#
+# The host requirement is Docker only: Go runs in the stock golang service
+# container, which drives the host daemon through the mounted socket, so it
+# cannot conflict with a vfox-managed toolchain. Rootless Docker users point
+# DOCKER_SOCK at their user socket:
+#
+#   DOCKER_SOCK="$XDG_RUNTIME_DIR/docker.sock" docker compose -f ... run --rm e2e
+#
+# Every knob below forwards only when set in the caller's env; empty means
+# "use the built-in default" (see matrix.go).
+
+services:
+  e2e:
+    image: golang:1.26.8
+    working_dir: /work/tests/e2e/linux
+    volumes:
+      - ${DOCKER_SOCK:-/var/run/docker.sock}:/var/run/docker.sock
+      - ../../..:/work
+      - e2e-go-modcache:/go/pkg
+    environment:
+      # Ryuk (the reaper sidecar) is disabled on purpose: it exposes a port on
+      # the host daemon and waits for it to be dialable, which fails when the
+      # suite itself runs in a container (Docker-out-of-Docker), especially
+      # under rootless Docker where containers cannot hairpin back to
+      # host-published ports. Every test container is terminated explicitly
+      # via t.Cleanup instead; leftovers from killed runs share the
+      # vfox-flutter-e2e- name prefix for easy pruning.
+      TESTCONTAINERS_RYUK_DISABLED: "true"
+      ARCH: ${ARCH:-}
+      E2E_MAX_JOBS: ${E2E_MAX_JOBS:-}
+      VFOX_VERSION: ${VFOX_VERSION:-}
+      FLAVOR: ${FLAVOR:-}
+      MIRROR: ${MIRROR:-}
+      FLUTTER_VERSION: ${FLUTTER_VERSION:-}
+      OHOS_VERSION: ${OHOS_VERSION:-}
+      VFOX_FLUTTER_GITHUB_MIRROR: ${VFOX_FLUTTER_GITHUB_MIRROR:-}
+      E2E_RETRY_ATTEMPTS: ${E2E_RETRY_ATTEMPTS:-}
+    command: ["go", "test", "-v", "-timeout", "55m", "-run", "TestE2E", "./..."]
+
+volumes:
+  e2e-go-modcache: