Documentation: Correct skopeo/podman usage - both rpm-ostree and apt-layer use podman as primary container runtime

docs/apt-layer/skopeo.md

@@ -40,14 +40,20 @@ skopeo inspect docker://ubuntu:24.04
 
 ## Overview
 
-apt-layer uses [skopeo](https://github.com/containers/skopeo) for OCI (Open Container Initiative) container image operations, mirroring the approach used by rpm-ostree. Skopeo is a command line utility that performs various operations on container images and image repositories without requiring the user to run a container daemon.
+apt-layer uses [skopeo](https://github.com/containers/skopeo) for OCI (Open Container Initiative) container image operations, mirroring the approach used by rpm-ostree. Both rpm-ostree and apt-layer use **podman as their primary container runtime** and **skopeo specifically for OCI operations**.
 
-**Key Role:** Skopeo serves as the primary OCI tool in apt-layer for:
+**Key Role:** Skopeo serves as the specialized OCI tool in apt-layer for:
 - Container image inspection and validation
 - Image copying between registries and local storage
 - Image format conversion (OCI ↔ ComposeFS)
 - Registry authentication and signature verification
 
+**Container Runtime:** Podman serves as the primary container runtime for:
+- Running containers for package installation
+- Building and managing container images
+- Container lifecycle management
+- Interactive development and testing
+
 ---
 
 ## Package Structure
@@ -82,25 +88,43 @@ sudo dnf install -y skopeo
 
 ## Skopeo Usage in apt-layer
 
-### 1. OCI Tool Priority
+### 1. Tool Usage Strategy
 
-apt-layer uses a priority-based approach for OCI operations:
+apt-layer and rpm-ostree use a specialized approach for different types of operations:
 
-1. **skopeo** (preferred) - For OCI operations only
+**OCI Operations (skopeo):**
-2. **podman** (fallback) - For container runtime operations
+- Image inspection and validation
-3. **docker** (alternative) - For container runtime operations
+- Image copying between registries
+- Image format conversion
+- Signature verification
+- Registry operations without running containers
+
+**Container Runtime Operations (podman):**
+- Running containers for package installation
+- Building and managing container images
+- Container lifecycle management
+- Interactive development and testing
 
 ```bash
-# apt-layer automatically detects and uses skopeo when available
+# apt-layer automatically detects and uses the appropriate tool
 if command -v skopeo &> /dev/null; then
     OCI_TOOL="skopeo"
     log_info "Using skopeo for OCI operations" "apt-layer"
 elif command -v podman &> /dev/null; then
     OCI_TOOL="podman"
-    log_info "Using podman for OCI operations" "apt-layer"
+    log_info "Using podman for OCI operations (fallback)" "apt-layer"
 else
     OCI_TOOL="docker"
-    log_info "Using docker for OCI operations" "apt-layer"
+    log_info "Using docker for OCI operations (fallback)" "apt-layer"
+fi
+
+# Container runtime is always podman when available
+if command -v podman &> /dev/null; then
+    CONTAINER_RUNTIME="podman"
+    log_info "Using podman as container runtime" "apt-layer"
+else
+    CONTAINER_RUNTIME="docker"
+    log_info "Using docker as container runtime" "apt-layer"
 fi
 ```
 
@@ -159,11 +183,14 @@ apt-layer --oci-info ubuntu:24.04
 
 **Authentication with registries:**
 ```bash
-# Login to registry (handled by podman/docker)
+# Login to registry (handled by podman)
 podman login myregistry.com
 
 # skopeo uses the same authentication
 skopeo copy docker://myregistry.com/image:tag dir:/local/path
+
+# Both podman and skopeo share authentication configuration
+# from ~/.docker/config.json or ~/.config/containers/auth.json
 ```
 
 ---
@@ -184,19 +211,29 @@ skopeo copy docker://myregistry.com/image:tag dir:/local/path
 - Cannot build images
 - Limited to OCI operations
 
-### Container Runtimes (podman/docker)
+### Podman (Primary Container Runtime)
 
 **Use Cases:**
-- Running containers
+- Running containers for package installation
-- Building images
+- Building and managing container images
 - Container lifecycle management
-- Interactive development
+- Interactive development and testing
+- OCI operations (when skopeo unavailable)
 
 **Integration:**
-- apt-layer uses container runtimes for package installation
+- apt-layer uses podman as the primary container runtime (like rpm-ostree)
-- skopeo handles OCI operations
+- skopeo handles specialized OCI operations
 - Both work together in the apt-layer ecosystem
 
+### Docker (Fallback Container Runtime)
+
+**Use Cases:**
+- Running containers when podman unavailable
+- Building images when podman unavailable
+- Container operations in environments without podman
+
+**Note:** apt-layer and rpm-ostree prefer podman over docker for container operations
+
 ---
 
 ## OCI Integration Workflow
@@ -254,10 +291,10 @@ apt-layer ostree compose export my-deployment myregistry/deployment:latest
 ### 2. Container-based Package Installation
 
 ```bash
-# Use OCI image as base for package installation
+# Use OCI image as base for package installation (uses podman)
 apt-layer --container ubuntu:24.04 my-dev/24.04 vscode git
 
-# Export result back to OCI
+# Export result back to OCI (uses skopeo)
 apt-layer --oci-export my-dev/24.04 myregistry/dev:latest
 ```
 
@@ -302,6 +339,7 @@ fi
 if ! skopeo copy "docker://$source" "docker://$destination"; then
     log_error "Authentication failed or insufficient permissions" "apt-layer"
     log_info "Try: podman login $registry" "apt-layer"
+    log_info "Note: podman and skopeo share authentication configuration" "apt-layer"
     return 1
 fi
 ```
@@ -367,7 +405,7 @@ insecure = true
 **1. Authentication Errors:**
 ```bash
 # Error: authentication required
-# Solution: Login to registry
+# Solution: Login to registry (podman and skopeo share auth)
 podman login myregistry.com
 ```
 
@@ -404,11 +442,12 @@ apt-layer --oci-import ubuntu:24.04 my-base/24.04
 
 ## Integration Notes
 
-- **OCI-First Approach:** apt-layer prioritizes skopeo for OCI operations, using container runtimes only when necessary
+- **Podman-First Approach:** apt-layer uses podman as the primary container runtime (like rpm-ostree)
+- **Skopeo for OCI:** skopeo handles specialized OCI operations (inspection, copying, conversion)
 - **ComposeFS Integration:** Seamless conversion between OCI and ComposeFS formats
 - **Registry Support:** Full support for Docker Hub, private registries, and local storage
 - **Signature Verification:** Built-in support for image signatures and verification
-- **Authentication:** Shared authentication with podman/docker for consistent experience
+- **Authentication:** Shared authentication between podman and skopeo for consistent experience
 - **Error Handling:** Comprehensive error handling with helpful diagnostic messages
 
 ---