[PL-68044] update: Docker configuration for container-based steps (#100903)

* 636bd4 [PL-68044] update: Docker configuration for container-based steps

Author: vishal-av

docs/platform/delegates-v2/delegate-overview.md

@@ -7,13 +7,13 @@ sidebar_label: Overview
 
 :::warning Closed Beta
 
-The new Harness Delegate is currently in closed beta and is available to select customers only. Access is determined by the product team based on current [supported use cases and steps](./install-delegate-2-0#whats-supported).
+The new Harness Delegate is currently in closed beta and available only to select customers. The product team determines access based on current [supported use cases and steps](./install-delegate-2-0#whats-supported).
 
 :::
 
-The new Harness Delegate is a lightweight service that runs in your infrastructure to execute pipeline work. Unlike the legacy delegate, which is deployed as a container application in Kubernetes or Docker environments, the new delegate uses a transaction-based execution model where stages are executed as a sequence of initialization, execution, and cleanup tasks. This model provides consistent stage execution across different infrastructure types and ensures reliable cleanup of resources created during stage execution.
+The new Harness Delegate is a lightweight service that runs in your infrastructure to execute pipeline work. Unlike the legacy delegate, which is deployed as a container application in Kubernetes or Docker environments, the new delegate uses a transaction-based execution model, with stages executed as a sequence of initialization, execution, and cleanup tasks. This model provides consistent stage execution across different infrastructure types and ensures reliable cleanup of resources created during stage execution.
 
-The new delegate operates alongside the legacy delegate. The legacy delegate continues to support the full range of Harness modules and capabilities, while the new delegate focuses on CI pipelines with a unified task framework optimized for local machine execution.
+The new delegate operates alongside the legacy delegate. The legacy delegate continues to support the full range of Harness modules and capabilities. In contrast, the new delegate focuses on CI pipelines with a unified task framework optimized for local machine execution.
 
 ## Architecture overview
 
@@ -23,15 +23,15 @@ The new delegate implements a multi-layered task execution framework that separa
 
 The delegate task framework consists of three distinct layers:
 
-- **Transportation layer**: Handles routing of tasks to delegates and manages scheduling configuration including timeouts, retries, and cron settings. This layer operates in Harness Manager.
+- **Transportation layer**: Handles routing of tasks to delegates and manages scheduling configuration, including timeouts, retries, and cron settings. This layer operates in Harness Manager.
 - **Driver layer**: Manages launching and executing tasks on different platforms and infrastructures such as local Docker, VM pools, and Kubernetes clusters. This layer is implemented in the delegate.
 - **Task layer**: Executes the actual step logic through module services and plugins. This layer is shared between Harness Manager and the delegate.
 
 This separation ensures each component is responsible for a focused set of concerns, making the system more maintainable and extensible.
 
 ### Transactional execution model
 
-The core concept in the new delegate is that each CI stage is modeled as a **transaction**. A transaction provides a shared state boundary for all tasks within a stage and guarantees cleanup of resources created during execution.
+The core concept in the new delegate is that each CI stage is modeled as a **transaction**. A transaction provides a shared state boundary for all tasks within a stage and guarantees the cleanup of resources created during execution.
 
 Transactional execution is implemented through three task types:
 
@@ -61,16 +61,18 @@ For more information about selector-based routing, go to [Use delegate selectors
 
 ## Secrets management
 
-The new delegate integrates with customer secret engines to fetch and inject secrets into task execution. Secret identifiers are provided as part of the task request, and secret expressions in the task payload are automatically replaced with decrypted values at runtime. Secrets are never persisted to disk or written to logs in plain text. The delegate automatically masks sensitive strings in all log output to prevent accidental disclosure.
+The new delegate integrates with customer secret engines to fetch and inject secrets into the task execution process. Secret identifiers are provided as part of the task request, and secret expressions in the task payload are automatically replaced with decrypted values at runtime. Secrets are never persisted to disk or written to logs in plain text. The delegate automatically masks sensitive strings in all log output to prevent accidental disclosure.
 
 ## Capacity management and queuing
 
 The new delegate introduces stage-level capacity management through the `MAX_STAGES` configuration setting. This setting limits the number of concurrent stages a delegate can execute. When a delegate reaches its capacity limit, additional stage requests are queued on the server side until capacity becomes available.
 
-This approach prevents resource exhaustion on the host machine and provides predictable performance characteristics. The queuing mechanism ensures work is not lost and will be processed as soon as delegate capacity frees up.
+This approach prevents resource exhaustion on the host machine and provides consistent performance. The queuing mechanism ensures work is not lost and is processed as soon as delegate capacity becomes available.
 
 Task cancellation is supported for local (Docker) infrastructure, allowing running tasks to be terminated when a pipeline is aborted or canceled.
 
+![Queuing](./static/queuing.png)
+
 ## Standalone tasks
 
 Not all delegate tasks fit the transactional model. The new delegate supports standalone tasks through the CGI (Common Gateway Interface) driver. CGI is a protocol for executing binaries through an HTTP interface, suitable for lightweight synchronous operations that don't require the full transaction lifecycle.
@@ -85,7 +87,7 @@ Remote logging to centralized services can be enabled through configuration. All
 
 ## Legacy task support
 
-When integration with legacy delegate functionality is required, the new delegate can utilize a delegate sidecar mechanism. The sidecar runs alongside the new delegate and handles execution of specific tasks that require legacy delegate implementations. This bridge mechanism enables gradual migration and ensures compatibility during the transition period.
+When integration with legacy delegate functionality is required, the new delegate can use a delegate-sidecar mechanism. The sidecar runs alongside the new delegate and handles execution of specific tasks that require legacy delegate implementations. This bridge mechanism enables gradual migration and ensures compatibility during the transition period.
 
 ## System requirements
 

docs/platform/delegates-v2/install-delegate-2-0.md

@@ -254,6 +254,24 @@ The delegate runs as a user service (LaunchAgent), not a system service. It only
 2. Edit the config: `nano ~/.harness-delegate/config.env`
 3. Start the service: `./delegate start`
 
+**Docker configuration for container-based steps:**
+
+If you plan to use Docker with container-based CI steps on macOS, you need to configure your Docker Desktop or Rancher Desktop settings to avoid permission-related issues. The delegate requires proper filesystem access between your local machine and the Docker VM.
+
+For optimal compatibility, configure the following settings in your Docker runtime preferences:
+
+1. **Filesystem Mount Type**: Select **reverse-sshfs** as your mount type
+   - In Rancher Desktop: Go to **Preferences** > **Virtual Machine** > **Volumes** tab  
+   - Choose reverse-sshfs instead of 9p or virtiofs
+
+2. **Virtual Machine Type**: Select **QEMU** as your emulation type
+   - In Rancher Desktop: Go to **Preferences** > **Virtual Machine** > **Emulation** tab
+   - Choose the QEMU option instead of VZ (Apple Virtualization framework)
+
+![Rancher Desktop Preferences Configuration](./static/rancher-desktop-preferences.png)
+
+These settings ensure proper permission mapping between your local filesystem and the Docker VM. Without them, you may encounter "Permission denied" errors when running containerized steps, as the default mount configurations don't always map filesystem permissions correctly.
+
 **Proxy configuration:**
 
 If you need proxy settings, add them to `~/.harness-delegate/config.env`. See [Configure Delegate Proxy Settings](/docs/platform/delegates/manage-delegates/configure-delegate-proxy-settings).