From 5f555b8b91ec610c9151d15a4d73638f982453d2 Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Fri, 15 Aug 2025 16:09:17 -0700 Subject: [PATCH] move windows section --- development/contributing.mdx | 136 +++++++++++++++++------------------ 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/development/contributing.mdx b/development/contributing.mdx index 00ccd39..1ea39bb 100644 --- a/development/contributing.mdx +++ b/development/contributing.mdx @@ -76,74 +76,6 @@ Below is an example if you're working on the Pangolin repository. 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) @@ -255,6 +187,74 @@ Local development requires more setup and may have environment-specific issues. +## 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. + + + ## Component Development ### Gerbil