refactor: simplify socket detection to default to Docker

Simplified container runtime socket configuration based on code review feedback. Docker is now the default with Podman as an explicit opt-in. Changes: - Simplified socket mount from complex nested fallback to simple default - Before: ${DOCKER_SOCKET:-${XDG_RUNTIME_DIR:-/run/user/1000}/podman/podman.sock} - After: ${DOCKER_SOCKET:-/var/run/docker.sock} - Docker works out of the box with no environment variables needed - Podman users set: export DOCKER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock - Updated CONTAINER_RUNTIME.md to reflect simplified approach - Fixed worker-file-processing-v2 command structure to match other workers (entrypoint + command pattern instead of array with binary) Benefits: - Cleaner default configuration for majority Docker users - Explicit opt-in for Podman users - Addresses CodeRabbit review concerns about socket fallback logic 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Zipstack · hari-kuriakose · Oct 18, 2025 · Oct 23, 2025 · Oct 23, 2025 · Oct 23, 2025
commit 3a3f0722eecc9650ba3e232b07b991e4e1038da3
diff --git a/docker/CONTAINER_RUNTIME.md b/docker/CONTAINER_RUNTIME.md
@@ -1,22 +1,22 @@
 # Container Runtime Support (Docker & Podman)
 
-The Unstract docker-compose configuration supports both **Docker** and **Podman** automatically.
+The Unstract docker-compose configuration supports both **Docker** (default) and **Podman**.
 
-## Automatic Detection
+## Socket Detection
 
-By default, the configuration will automatically detect and use the appropriate socket:
-- **Podman rootless**: `/run/user/$UID/podman/podman.sock`
-- **Docker**: `/var/run/docker.sock`
+The configuration defaults to Docker and supports Podman via environment variable:
+- **Docker**: Default (`/var/run/docker.sock`) - no configuration needed
+- **Podman**: Set `DOCKER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock`
 
 ## Using Docker
 
-Just run docker-compose commands normally:
+Docker works out of the box with no additional configuration:
 
 ```bash
 VERSION=main docker-compose -f docker-compose.yaml up -d
 ```
 
-No environment variables needed - Docker socket at `/var/run/docker.sock` will be used automatically.
+The Docker socket at `/var/run/docker.sock` is used automatically.
 
 ## Using Podman
 
@@ -36,13 +36,16 @@ No environment variables needed - Docker socket at `/var/run/docker.sock` will b
 
 ### Run with Podman
 
+Set the `DOCKER_SOCKET` environment variable to point to Podman socket, then run podman-compose:
+
 ```bash
+export DOCKER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock
 VERSION=main podman-compose -f docker-compose.yaml up -d
 ```
 
-The Podman socket will be automatically detected via `$XDG_RUNTIME_DIR/podman/podman.sock`.
+**Note**: The `DOCKER_SOCKET` environment variable must be set to use Podman instead of the default Docker socket.
 
-## Manual Override
+## Custom Socket Path
 
 If you need to specify a custom socket path, set the `DOCKER_SOCKET` environment variable:
 
@@ -51,7 +54,7 @@ If you need to specify a custom socket path, set the `DOCKER_SOCKET` environment
 export DOCKER_SOCKET=/custom/path/docker.sock
 VERSION=main docker-compose -f docker-compose.yaml up -d
 
-# Example: Custom Podman socket location
+# Example: Alternative Podman socket location
 export DOCKER_SOCKET=/run/user/$(id -u)/podman/podman.sock
 VERSION=main podman-compose -f docker-compose.yaml up -d
 ```
@@ -114,30 +117,30 @@ This is the Traefik HTTP port for Podman rootless compatibility.
 
 ## Socket Path Priority
 
-The configuration uses this priority order:
+The configuration uses this simple priority:
+
+1. `$DOCKER_SOCKET` - if explicitly set (use this for Podman or custom paths)
+2. `/var/run/docker.sock` - default (Docker standard socket)
 
-1. `$DOCKER_SOCKET` - if explicitly set
-2. `$XDG_RUNTIME_DIR/podman/podman.sock` - for Podman rootless
-3. `/run/user/1000/podman/podman.sock` - fallback for Podman
-4. Falls back to default compose behavior (typically `/var/run/docker.sock`)
+**Docker**: No configuration needed - uses default socket
+**Podman**: Set `export DOCKER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock`
 
 ## Technical Details
 
 The docker-compose files use this volume mount configuration:
 
 ```yaml
 volumes:
-  - ${DOCKER_SOCKET:-${XDG_RUNTIME_DIR:-/run/user/1000}/podman/podman.sock}:/var/run/docker.sock
+  - ${DOCKER_SOCKET:-/var/run/docker.sock}:/var/run/docker.sock
 ```
 
 This means:
-- If `DOCKER_SOCKET` is set → use that
-- Else if `XDG_RUNTIME_DIR` is set → use `$XDG_RUNTIME_DIR/podman/podman.sock`
-- Else → use `/run/user/1000/podman/podman.sock`
+- If `DOCKER_SOCKET` is set → use that path (for Podman or custom Docker socket)
+- Else → use `/var/run/docker.sock` (Docker default)
 
-For Docker, you can set:
+**For Podman users:**
 ```bash
-export DOCKER_SOCKET=/var/run/docker.sock
+export DOCKER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock
 ```
 
-But it's usually not necessary since Docker Compose will use `/var/run/docker.sock` by default when the variable is unset.
+This overrides the default Docker socket with the Podman socket path.
diff --git a/docker/docker-compose-dev-essentials.yaml b/docker/docker-compose-dev-essentials.yaml
@@ -82,10 +82,10 @@ services:
       # The Web UI (enabled by --api.insecure=true)
       - "8080:8080"
     volumes:
-      # Universal socket mount - works with both Docker and Podman
-      # Podman rootless: /run/user/$UID/podman/podman.sock
-      # Docker: /var/run/docker.sock
-      - ${DOCKER_SOCKET:-${XDG_RUNTIME_DIR:-/run/user/1000}/podman/podman.sock}:/var/run/docker.sock
+      # Socket mount for container runtime (defaults to Docker)
+      # Docker: /var/run/docker.sock (default)
+      # Podman: Set DOCKER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock
+      - ${DOCKER_SOCKET:-/var/run/docker.sock}:/var/run/docker.sock
       # Proxy overrides for components run directly in Docker host
       - ./proxy_overrides.yaml:/proxy_overrides.yaml
     # Since any proxy overrides need to point to Docker host for relevant routes.

diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml
@@ -231,10 +231,10 @@ services:
       - ../runner/.env
     volumes:
       - ./workflow_data:/data
-      # Universal socket mount - works with both Docker and Podman
-      # Podman rootless: /run/user/$UID/podman/podman.sock
-      # Docker: /var/run/docker.sock
-      - ${DOCKER_SOCKET:-${XDG_RUNTIME_DIR:-/run/user/1000}/podman/podman.sock}:/var/run/docker.sock
+      # Socket mount for container runtime (defaults to Docker)
+      # Docker: /var/run/docker.sock (default)
+      # Podman: Set DOCKER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock
+      - ${DOCKER_SOCKET:-/var/run/docker.sock}:/var/run/docker.sock
     depends_on:
       - redis
       - rabbitmq
@@ -311,22 +311,8 @@ services:
     image: unstract/worker-unified:${VERSION}
     container_name: unstract-worker-file-processing-v2
     restart: unless-stopped
-    # command: ["file-processing"]
-    command:
-      [
-        ".venv/bin/celery",
-        "-A",
-        "worker",
-        "worker",
-        "--queues=file_processing,api_file_processing,file_processing_priority",
-        "--loglevel=INFO",
-        "--pool=prefork",
-        "--concurrency=4",
-        "--prefetch-multiplier=1",
-        "--without-gossip",
-        "--without-mingle",
-        "--without-heartbeat",
-      ]
+    entrypoint: .venv/bin/celery
+    command: "-A worker worker --queues=file_processing,api_file_processing,file_processing_priority --loglevel=INFO --pool=prefork --concurrency=4 --prefetch-multiplier=1 --without-gossip --without-mingle --without-heartbeat"
     ports:
       - "8087:8082"
     env_file: