Add steps to make local testing of PiP container work

CI_CD_PIPELINE_SETUP_GUIDE.md

@@ -940,6 +940,64 @@ sudo journalctl -u forgejo-runner.service -f --no-pager
 - Check network: Ensure the runner can reach your Forgejo instance
 - Restart service: `sudo systemctl restart forgejo-runner.service`
 
+### Step 6: Set Up Podman Host Socket Service
+
+**CRITICAL**: Before proceeding with PiP containers, you must start the Podman host socket service that provides the UNIX socket for container communication.
+
+#### 6.1 Start Podman Host Socket Service
+
+```bash
+# Switch to CI_SERVICE_USER (who will run the socket service)
+sudo su - CI_SERVICE_USER
+
+# Enable lingering for CI_SERVICE_USER to allow systemd user services to start at boot
+sudo loginctl enable-linger CI_SERVICE_USER
+
+# Start the podman-host-socket service
+systemctl --user enable --now podman-host-socket.service
+
+# Verify the service is running
+systemctl --user status podman-host-socket.service
+
+# Check that the UNIX socket was created
+ls -la /run/user/$(id -u)/podman-host/podman.sock
+# Should show: srw-rw---- 1 CI_SERVICE_USER CI_SERVICE_USER 0 ... /run/user/999/podman-host/podman.sock
+
+# Test socket connectivity
+podman --url unix:///run/user/$(id -u)/podman-host/podman.sock version
+```
+
+**What this does**:
+- **Enables lingering**: Allows systemd user services to start automatically
+- **Starts socket service**: Creates the UNIX socket that PiP containers will use
+- **Verifies operation**: Ensures the socket is properly created and accessible
+
+**If you see cgroup warnings**:
+```bash
+# If you see warnings about systemd user session, enable lingering properly
+sudo loginctl enable-linger $(id -u)
+
+# Verify lingering is enabled
+loginctl show-user $(whoami) | grep Linger
+# Should show: Linger=yes
+```
+
+#### 6.2 Verify Socket Permissions
+
+```bash
+# Ensure proper socket permissions (should be 660)
+chmod 660 /run/user/$(id -u)/podman-host/podman.sock
+
+# Verify socket is accessible
+podman --url unix:///run/user/$(id -u)/podman-host/podman.sock info
+```
+
+**Expected Output**:
+- Socket service should show "active (running)"
+- UNIX socket should exist at `/run/user/999/podman-host/podman.sock`
+- Socket should have permissions `srw-rw----`
+- Podman commands should work through the socket
+
 ### Environment Variables for PiP Scripts
 
 Before proceeding with Section 7, you need to understand the environment variables used by the PiP (Podman-in-Podman) scripts. These variables control the behavior of `secure_pip_setup.sh` and `pip_ready.sh` and are automatically set in CI environments but may need manual configuration for local testing.
@@ -948,12 +1006,15 @@ Before proceeding with Section 7, you need to understand the environment variabl
 
 **1. `PODMAN_CLIENT_IMG_DIGEST` (REQUIRED)**
 - **Purpose**: Pinned image digest for the Podman client container used in PiP
-- **Format**: Must be a full digest reference (e.g., `quay.io/podman/stable@sha256:...`)
+- **Format**: Must be a full digest reference including the registry URL (e.g., `quay.io/podman/stable@sha256:...`)
 - **How to obtain**:
   ```bash
   # Get Podman client image digest
-  podman manifest inspect quay.io/podman/stable:latest | jq -r '.manifests[0].digest'
+  DIGEST=$(podman manifest inspect quay.io/podman/stable:latest | jq -r '.manifests[0].digest')
-  # Result: quay.io/podman/stable@sha256:...
+  # Combine with registry URL to create full digest reference
+  export PODMAN_CLIENT_IMG_DIGEST="quay.io/podman/stable@${DIGEST}"
+  echo "PODMAN_CLIENT_IMG_DIGEST=${PODMAN_CLIENT_IMG_DIGEST}"
+  # Result: quay.io/podman/stable@sha256:5dd9f78bd233970ea4a36bb65d5fc63b7edbb9c7f800ab7901fa912564f36415
   ```
 - **Security Importance**: Prevents supply chain attacks by ensuring only verified images are used
 
@@ -2023,27 +2084,38 @@ Go to your Forgejo repository and add these secrets in **Settings → Secrets an
 
 - **`PODMAN_CLIENT_IMG_DIGEST`**: Used for secure ephemeral PiP containers in CI
   ```bash
-  # Get Podman client image digest
+  # Get Podman client image digest and create full reference
-  podman manifest inspect quay.io/podman/stable:latest | jq -r '.manifests[0].digest'
+  DIGEST=$(podman manifest inspect quay.io/podman/stable:latest | jq -r '.manifests[0].digest')
-  # Result: quay.io/podman/stable@sha256:...
+  export PODMAN_CLIENT_IMG_DIGEST="quay.io/podman/stable@${DIGEST}"
+  echo "PODMAN_CLIENT_IMG_DIGEST=${PODMAN_CLIENT_IMG_DIGEST}"
+  # Result: quay.io/podman/stable@sha256:5dd9f78bd233970ea4a36bb65d5fc63b7edbb9c7f800ab7901fa912564f36415
   ```
 
 - **`RUST_IMG_DIGEST`**: Used for Rust backend testing and building
   ```bash
-  # Get Rust image digest  
+  # Get Rust image digest and create full reference
-  podman manifest inspect docker.io/library/rust:latest | jq -r '.manifests[0].digest'
+  DIGEST=$(podman manifest inspect docker.io/library/rust:latest | jq -r '.manifests[0].digest')
+  export RUST_IMG_DIGEST="docker.io/library/rust@${DIGEST}"
+  echo "RUST_IMG_DIGEST=${RUST_IMG_DIGEST}"
+  # Result: docker.io/library/rust@sha256:...
   ```
 
 - **`NODE_IMG_DIGEST`**: Used for Node.js frontend testing and building
   ```bash
-  # Get Node.js image digest
+  # Get Node.js image digest and create full reference
-  podman manifest inspect docker.io/library/node:latest | jq -r '.manifests[0].digest'
+  DIGEST=$(podman manifest inspect docker.io/library/node:latest | jq -r '.manifests[0].digest')
+  export NODE_IMG_DIGEST="docker.io/library/node@${DIGEST}"
+  echo "NODE_IMG_DIGEST=${NODE_IMG_DIGEST}"
+  # Result: docker.io/library/node@sha256:...
   ```
 
 - **`POSTGRES_IMG_DIGEST`**: Used for PostgreSQL database in integration tests
   ```bash
-  # Get PostgreSQL image digest
+  # Get PostgreSQL image digest and create full reference
-  podman manifest inspect docker.io/library/postgres:latest | jq -r '.manifests[0].digest'
+  DIGEST=$(podman manifest inspect docker.io/library/postgres:latest | jq -r '.manifests[0].digest')
+  export POSTGRES_IMG_DIGEST="docker.io/library/postgres@${DIGEST}"
+  echo "POSTGRES_IMG_DIGEST=${POSTGRES_IMG_DIGEST}"
+  # Result: docker.io/library/postgres@sha256:...
   ```
 
 **2. SSH Keys (Secure Deployment Access):**