From 4ea7d491e5ec2bdff51da444120166c0bf63e7a2 Mon Sep 17 00:00:00 2001 From: Leon Feng Date: Mon, 6 Nov 2023 19:21:41 +0400 Subject: [PATCH] feat(docs): expand the WSL guide (#52203) --- docs/how-to-setup-wsl.md | 118 +++++++++++++++++++++++++++++++++------ 1 file changed, 102 insertions(+), 16 deletions(-) diff --git a/docs/how-to-setup-wsl.md b/docs/how-to-setup-wsl.md index 7ba30dbae31..6b167329ae9 100644 --- a/docs/how-to-setup-wsl.md +++ b/docs/how-to-setup-wsl.md @@ -11,7 +11,7 @@ This guide covers some common steps with the setup of WSL2. Once some of the com ## Enable WSL -Follow the instructions on the [official documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10) to install WSL1 and followed by upgrading to WSL2. +Follow the instructions on the [official documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10) to install WSL2. ## Install Ubuntu @@ -21,6 +21,8 @@ Follow the instructions on the [official documentation](https://docs.microsoft.c > > While you may use other non-Debian-based distributions, they all come with their own 'gotchas' that are beyond the scope of this guide. + As of November 2023, Ubuntu and Debian are the only Linux distributions [officially supported by Playwright](https://playwright.dev/docs/intro#system-requirements), the end-to-end testing library used by freeCodeCamp. + 2. Update the dependencies for the OS ```console @@ -71,12 +73,12 @@ This makes it so that the containers run on the WSL side instead of running on W Once you have configured Docker Desktop to work with WSL2, follow these steps to start a MongoDB service: -1. Launch a new Ubuntu-18.04 terminal +1. Launch a new Ubuntu terminal -2. Pull `MongoDB 4.0.x` from Docker Hub +2. Pull MongoDB from Docker Hub. Please refer to the [Prerequisites](how-to-setup-freecodecamp-locally.md#Prerequisites) table for the current version of MongoDB used by freeCodeCamp. For example, if the version number is `5.0.x`, replace `` with `5.0` in the following two code snippets. ```console - docker pull mongo:4.0 + docker pull mongo: ``` 3. Start the MongoDB service at port `27017`, and configure it to run automatically on system restarts @@ -87,7 +89,7 @@ Once you have configured Docker Desktop to work with WSL2, follow these steps to -p 27017:27017 \ --name mongodb \ --restart unless-stopped \ - -d mongo:4.0 + -d mongo: ``` 4. You can now access the service from both Windows or Ubuntu at `mongodb://localhost:27017`. @@ -96,22 +98,14 @@ Once you have configured Docker Desktop to work with WSL2, follow these steps to We recommend you install the LTS release for Node.js with a node version manager - [nvm](https://github.com/nvm-sh/nvm#installing-and-updating). -Once installed use these commands to install and use the Node.js version as needed +Once installed use this command to install and use the latest Node.js LTS version: ```console nvm install --lts - -# OR -# nvm install - -nvm install 14 - -# Usage -# nvm use - -nvm use 12 ``` +For instructions on installing and using a different version of Node.js, please refer to the [nvm docs](https://github.com/nvm-sh/nvm#usage). + Node.js comes bundled with `npm`, which you can use to install `pnpm`: ```console @@ -126,6 +120,98 @@ Now that you have installed the pre-requisites, follow [our local setup guide](h > > Please note, at this time the setup for Cypress tests (and related GUI needs) is a work in progress. You should still be able to work on most of the codebase. +## Optimize Windows and WSL + + > [!NOTE] + > + > The following tips were collected from across the web and have not gone through vigorous testing. Your mileage may vary. + +### Adjust processer scheduling for background services + +This may reduce incidents of Docker containers crashing due to lack of resources. + +Open the System Properties control panel by pressing Win + R and entering `sysdm.cpl` + +
+ + Enter sysdm.cpl in the Run dialog (screenshot) + +
+ Enter `sysdm.cpl` in the Run dialog +
+
+ +Go to Advanced -> Performance -> Settings… + +
+ + Performance Settings button under Advanced tab in System Properties (screenshot) + +
+ Performance Settings button under Advanced tab in System Properties +
+
+ +Under Advanced -> Processor scheduling, choose "Background services". Do not close the window. Continue to the next tip. + +
+ + Background services radio button under Advanced tab in Performance Options (screenshot) + +
+ Background services radio button under Advanced tab in Performance Options +
+ +### Increase the size of Windows paging file for the system drive + +Under Advanced -> Virtual memory, click "Change…" + +
+ + Change virtual memory button under Advanced tab in Performance Options (screenshot) + +
+ Change virtual memory button under Advanced tab in Performance Options +
+
+ +Choose "Custom size". Set the initial size to 1.5x and the maximum size to 3x of your physical memory. Then click "Set". + +
+ + Set custom size button in Virtual Memory window (screenshot) + +
+ Set custom size button in Virtual Memory window +
+ +### Increase the size of memory allocated to WSL + +Create a [`.wslconfig` file](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#configuration-setting-for-wslconfig) in your [`%UserProfile%` directory](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#wslconfig) (typically `C:\Users\\.wslconfig`). Please read the [WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#configuration-setting-for-wslconfig) carefully and replace `x` with values that suit your own needs: + +```ini +# Settings apply across all Linux distros running on WSL 2 +[wsl2] + +# How much memory to assign to the WSL 2 VM. The default value might not be enough +memory=xGB + +# How much swap space to add to the WSL 2 VM, default is 25% of available RAM +swap=xGB +``` + +### Increase Node.js max old space size + +This fixes the ["JavaScript heap out of memory" error](https://stackoverflow.com/a/54456814) with ESLint. Add the following to your `~/.bashrc` or `~/.zshrc`: + +```sh +export NODE_OPTIONS="--max-old-space-size=4096" +``` + +### Avoid `pnpm run test` + +Instead, use the script [appropriate to your PR](https://forum.freecodecamp.org/t/wsl-performance-issues-while-working-on-the-codebase/644215/2#:~:text=usually%2C%20you%20just%20want%20to%20test%20something%20specific%20to%20either%20the%20curriculum%20or%20the%20client%20or%20the%20api%20-%20almost%20never%20all%203.); either `pnpm run test:api`, `pnpm run test:curriculum`, or `pnpm run test-client`. + ## Useful Links - [A WSL2 Dev Setup with Ubuntu 20.04, Node.js, MongoDB, VS Code, and Docker](https://hn.mrugesh.dev/wsl2-dev-setup-with-ubuntu-nodejs-mongodb-and-docker) - an article by Mrugesh Mohapatra (Staff Developer at freeCodeCamp.org)