From d9631c234287c1aea2fb9f7eaa5ec00ad437b298 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Sch=C3=A4fer?= Date: Fri, 8 Aug 2025 16:45:06 +0200 Subject: [PATCH] add WSL-based hot reload setup instructions for Windows users --- development/contributing.mdx | 70 ++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/development/contributing.mdx b/development/contributing.mdx index 0d51e04..00ccd39 100644 --- a/development/contributing.mdx +++ b/development/contributing.mdx @@ -74,6 +74,76 @@ Below is an example if you're working on the Pangolin repository. ## Pangolin Development Setup +Choose your preferred development approach. We strongly recommend **Docker Compose** for the most consistent experience across all platforms. + +### Windows Development Considerations + + +Windows users with Docker Desktop + WSL2: File change detection may not work properly when project files are stored on the Windows filesystem. + + + + + **Best performance and compatibility** + + + - **Where to store your project files:** + - For best performance, always store your project inside the Linux filesystem of your Docker or Default WSL2 instance, e.g. `/home//pangolin`. + - If other WSL instances are used, ensure the Docker Desktop WSL integration is enabled for that distribution. + - For further information, see Link Section below. + + - **Accessing WSL2 files from Windows:** + - You can access your WSL2 home directory from Windows using the UNC path: `\\wsl$\\home\\pangolin` (replace `` with your actual WSL distribution, e.g. `Ubuntu-22.04`). + - This path works in Windows Explorer, VS Code, and other Windows applications. You can drag & drop files, create shortcuts, or map a network drive for convenience. + - **Note:** This UNC path is for Windows tools only. Do not use it for Docker container mounts. + + - **How to mount WSL2 files in Docker containers:** + - Always use the absolute Linux path from inside WSL2 for Docker volumes. This is the only method fully supported and recommended by Docker. + - **Correct Docker Compose example:** + ```yaml + services: + app: + volumes: + - /home//pangolin:/app + ``` + - **Correct docker run example:** + ```bash + docker run -v /home//pangolin:/app my-image + ``` + - **Never use `\\wsl$` or Windows paths** (e.g. `/mnt/c/...`) for Docker volumes when running with the WSL2 backend. This is not supported and can lead to poor performance or errors. + - File watchers and hot reload works natively when your project is inside the WSL2 filesystem and mounted using the Linux path. + + You may want to use the [VS Code Remote - WSL extension](https://code.visualstudio.com/docs/remote/wsl) or [VS Code Remote - SSH Extension](https://code.visualstudio.com/docs/remote/ssh) to open your project folder directly in VSCode from the WSL/Remote Filesystem for seamless Development. + + + **Reference Links** + - [WSL Docker Best Practices](https://docs.docker.com/desktop/features/wsl/best-practices/) + - [Use WSL for Development](https://docs.docker.com/desktop/features/wsl/use-wsl/) + - [WSL2 Setup](https://docs.docker.com/desktop/features/wsl/) + + + + If you need to keep your files on the native Windows filesystem (`C:\Users\...`), enable **Polling Mode** for file watchers. + + Enable polling mode by adding the following environment variables to your `docker-compose.yml` or `.env` file: + + For `.env`: + ```env + WATCHPACK_POLLING=true + CHOKIDAR_USEPOLLING=true + ``` + + For `docker-compose.yml`: + ```yaml + environment: + - WATCHPACK_POLLING=true + - CHOKIDAR_USEPOLLING=true + ``` + + This increases CPU usage but ensures file watchers work properly. Polling mode is not required when working directly on the WSL filesystem. + + + ### Option 1: Docker Compose (Recommended)