diff --git a/docs/development/setup-recommended.md b/docs/development/setup-recommended.md index 21d693d54f..235700b8f2 100644 --- a/docs/development/setup-recommended.md +++ b/docs/development/setup-recommended.md @@ -752,6 +752,15 @@ WSL instance) is also usually helpful. ::::{tab-set} +:::{tab-item} Windows (WSL) +:sync: os-windows + +```{include} setup/wsl-troubleshoot.md + +``` + +::: + :::{tab-item} Windows (VM) :sync: os-windows-vm diff --git a/docs/development/setup/wsl-troubleshoot.md b/docs/development/setup/wsl-troubleshoot.md new file mode 100644 index 0000000000..12697a57b2 --- /dev/null +++ b/docs/development/setup/wsl-troubleshoot.md @@ -0,0 +1,75 @@ +WSL2 users often encounter issues where services fail to start or remain inactive. Follow the steps below to diagnose and resolve such problems. + +#### 1. Check the Status of the Service + +To verify if a service is running, use the following command: + +```console +$ systemctl status +``` + +If the service is inactive, you can attempt to start it with: + +```console +$ systemctl start +``` + +#### 2. Diagnose Port Conflicts + +Services like `postgresql` may fail to start due to port conflicts. These conflicts can be caused by: + +- Other services running in Windows. +- Services running in another WSL2 instance. + +#### Resolving Port Conflicts with Other WSL Instances + +To resolve port conflicts with another WSL2 instance, stop the conflicting instance using the following command: + +```console +> wsl -t +``` + +After stopping the conflicting instance, restart your WSL instance with: + +```console +> wsl -d +``` + +#### Resolving Port Conflicts with Services Running on Windows + +To resolve conflicts caused by Windows processes: + +1. Identify the process using the conflicting port by running: + +```console +> Get-Process -Id (Get-NetTCPConnection -LocalPort ).OwningProcess +``` + +2. If a process is found, terminate it using: + +```console +> taskkill /PID /F +``` + +3. Restart the Service or Enable Auto-Start + +After resolving port conflicts, try restarting the service using: + +```console +$ systemctl start +``` + +To ensure the service always starts on boot, enable it with: + +```console +$ systemctl enable +``` + +--- + +#### Additional Tips + +- Use `wsl --list` to view all running WSL2 instances and their states. +- Avoid overlapping port usage between WSL2 instances and Windows processes. +- Keep a record of services and their associated port numbers to prevent conflicts in the future. +- Ensure that you use a fresh WSL instance to setup the Zulip development environment to avoid dependency conflicts.