From 7ed5873a2ef44bba3598f887104e611656752eb2 Mon Sep 17 00:00:00 2001 From: "hankyo.chung" Date: Wed, 15 Apr 2026 09:19:42 +0900 Subject: [PATCH 1/2] docs: expand Rancher Desktop troubleshooting with WSL exit code 1 fix and required runtime docs --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2889f77..419205e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,11 @@ This setup works with any environment that supports `docker compose` (e.g. Docke ## Prerequisites -Install one of the following: +**Git** +- Windows: `winget install Git.Git` (or download from [git-scm.com](https://git-scm.com/)) +- Mac: `brew install git` + +**Container Runtime** (Install one of the following): **Docker Desktop** (paid for commercial use) @@ -17,7 +21,8 @@ Install one of the following: - Windows: `winget install suse.RancherDesktop` - Mac: `brew install --cask rancher` - - Select **dockerd (moby)** as the container runtime after installation → [Guide](https://docs.rancherdesktop.io/ui/preferences/container-engine/general) + +> **Important:** You MUST select **dockerd (moby)** as the container runtime after installation → [Guide](https://docs.rancherdesktop.io/ui/preferences/container-engine/general) > **Mac + Rancher Desktop:** The Docker socket path differs from the default. > Add the following to `~/.zshrc` to apply permanently: @@ -36,6 +41,7 @@ cd dart-services-compose cp .env.example .env # 3. Start simulator + build modules +# Note: Make sure Docker Desktop or Rancher Desktop is running first docker compose --profile build up -d ``` @@ -92,6 +98,83 @@ Images are hosted on GitHub Container Registry (GHCR) and pulled automatically o - [`ghcr.io/doosanrobotics/build-module-fw`](https://github.com/orgs/DoosanRobotics/packages/container/package/build-module-fw) - [`ghcr.io/doosanrobotics/build-module-ui`](https://github.com/orgs/DoosanRobotics/packages/container/package/build-module-ui) +## Troubleshooting + +### Rancher Desktop (Windows) + +If you encounter Docker connectivity errors or if the Rancher Desktop Diagnostics tab reports problems such as `Docker context is currently desktop-linux instead of default` or `C:\Windows\system32\wsl.exe exited with code 1`, try the following fixes in your terminal (PowerShell): + +1. **Conflicts between Docker Desktop and Rancher Desktop** + Running both simultaneously on Windows can cause Docker CLI confusion, WSL collisions, and port binding errors. + + **Fix**: We highly recommend **uninstalling Docker Desktop**. If you must keep both, ensure only *one* is running at a time and run `docker context use default`. + +2. **Set Default Docker Context** + Ensure Docker is pointing to the correct engine: + ```shell + docker context use default + ``` + +3. **Wake Up the Stopped WSL Distribution** + If your default WSL distribution (e.g., `Ubuntu`) is stopped, Rancher Desktop may fail to inject its background helpers. Manually wake it up by running: + ```shell + wsl -d Ubuntu -e true + ``` + After running this, check the Rancher Desktop Diagnostics tab again or restart Rancher Desktop. + +4. **Resolve `wsl.exe exited with code 1` (kubeconfig / WSL Error)** + If Rancher Desktop Diagnostics reports an error like `Error managing distribution Ubuntu-24.04:kubeconfig: C:\windows\system32\wsl.exe exited with code 1`, your WSL core might be outdated or stuck. Fix this by updating and forcefuly restarting WSL: + ```shell + wsl --update + wsl --shutdown + ``` + After updating, completely quit and relaunch Rancher Desktop. + +### Container Fails to Start Due to Windows Port Conflicts + +On Windows, services or previous Docker sessions may occupy required host ports, preventing containers from binding to them. Affected ports per service: + +| Service | Host Ports | +|---|---| +| `simulator` | 1122, 12345, 12360 (UDP), 3601, 502 | +| `build-module-fw` | 5022 | +| `build-module-ui` | 5023, 3002, 8089 (UDP) | + +**Step 1 — Identify which ports are in use:** + +```powershell +# Check if any required ports are already occupied +netstat -ano | Select-String "5023|3002|8089|5022|1122|12345|12360|3601|:502 " +``` + +Note the PID from the last column and identify the process: + +```powershell +Get-Process -Id +``` + +**Step 2 — Check for stale WSL2 port proxy rules:** + +```powershell +netsh interface portproxy show all +``` + +If you see entries for the above ports pointing to a WSL2 IP (e.g., `172.x.x.x`) but containers are not running, these are stale rules. Remove them: + +```shell +# Remove a specific stale rule (replace with the conflicting port number) +netsh interface portproxy delete v4tov4 listenport= listenaddress=0.0.0.0 +``` + +**Step 3 — Restart containers:** + +```shell +docker compose --profile build down +docker compose --profile build up -d +``` + +> **Tip:** If a Windows service (e.g., `svchost / iphlpsvc`) is holding the port, try restarting Docker or rebooting the machine to release the reservation. + ## License Copyright © Doosan Robotics. All rights reserved. From 67339a993e8a8e9082f07f27f8db9bb44d9cb98f Mon Sep 17 00:00:00 2001 From: "hankyo.chung" Date: Wed, 29 Apr 2026 09:52:32 +0900 Subject: [PATCH 2/2] docs: add troubleshooting steps for Rancher Desktop kubeconfig issues --- README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 419205e..77a2654 100644 --- a/README.md +++ b/README.md @@ -123,12 +123,22 @@ If you encounter Docker connectivity errors or if the Rancher Desktop Diagnostic After running this, check the Rancher Desktop Diagnostics tab again or restart Rancher Desktop. 4. **Resolve `wsl.exe exited with code 1` (kubeconfig / WSL Error)** - If Rancher Desktop Diagnostics reports an error like `Error managing distribution Ubuntu-24.04:kubeconfig: C:\windows\system32\wsl.exe exited with code 1`, your WSL core might be outdated or stuck. Fix this by updating and forcefuly restarting WSL: + If Rancher Desktop Diagnostics reports an error like `Error managing distribution Ubuntu: kubeconfig: C:\Windows\system32\wsl.exe exited with code 1`, this may be caused by a conflicting `~/.kube/config` file or an outdated WSL core. + + **Fix A: Conflicting `kubeconfig` file (invalid argument)** + Rancher Desktop attempts to create a symlink at `~/.kube/config` in your WSL distribution (e.g., `Ubuntu`) to point to its own cluster configuration. If a regular file or directory already exists at this path, the boot process will fail. Fix this by backing up or removing the file: + ```shell + wsl -d Ubuntu -- mv ~/.kube/config ~/.kube/config.bak + ``` + *(Note: Replace `Ubuntu` with your default WSL distribution name if it differs.)* + + **Fix B: Outdated or stuck WSL core** + If the issue persists, your WSL core might be outdated or stuck. Fix this by updating and forcefully restarting WSL: ```shell wsl --update wsl --shutdown ``` - After updating, completely quit and relaunch Rancher Desktop. + After applying either fix, completely quit and relaunch Rancher Desktop. ### Container Fails to Start Due to Windows Port Conflicts