- A device running Windows 10 updated to version 2004, build 19041 or greater. WSL 2 WILL NOT RUN on versions before this. You MUST update Windows to be on version 2004, build 19041 or greater to continue! Check out Updating Windows to Version 2004+
- A familiarity with your system's BIOS may be required. This is extremely important as you may need to adjust BIOS settings to complete the WSL install, particularly if your machine uses an AMD processor. You are not able to screen share within the BIOS environment and it will be different depending on the device you use. Therefore, it is ON YOU to be able to enter this environment and find the settings you will need to change. Modifying the incorrect settings in the BIOS can cause permanent hardware damage to your device, which we are not liable for. IF THIS SCARES YOU, WSL may not be the best option for you.
- A non-Windows 10 S Version of Windows 10
- A user account with administrative privilege to your local installation of Windows 10.
- A Microsoft Account with access to the Microsoft Store application. (All requirements are free, but are only available from the Microsoft Store)
- At least 25GB of free hard drive space
- At least 8GB of RAM (more is GREATLY preferable)
- A modern processor capable of running virtual environments - specifically processors with Intel Virtualization Technology (Intel VT) or AMD Virtualization (AMD-V) technology
- A fundamental understanding of Windows and Linux system administration and debugging.
A Windows 10 PC eligable to run WSL 2.
Running a Windows 10 Version older than 2004 or build lower than 19041? Check out:
Updating Windows to Version 2004+
If you run into issues during this process Microsoft has a collection of errors and their suggested fixes here and here. If your issue is not included in that documentation you can also search for your specific error on the WSL GitHub Issues page. If you've exhausted those resources try searching Google. If your issue remains unresolved reach out to an instructor for further guidance.
❗ Be prepared for there to not currently be a fix for your problem.Notion is an all-in-one workspace which all the course content will be hosted on. You can download Notion here. Be sure to select the Download for Windows option when it is given. ****Install it by opening the downloaded .exe file and completing the installation steps.
When the installation is complete open the Notion application. To do so, press the Windows Key to launch Windows Search and type Notion, then Select the Notion application by pressing Enter when it appears, as shown in the screenshot below.
Launching the Notion application using Windows Search. Get used to seeing this often; it's the fastest way to start applications on Windows!
When the application launches, you will be presented with a login screen. DO NOT select Continue with Apple or Continue with Google. Instead, enter the email you used to apply to General Assembly in the provided area and select Continue with email.
After doing so, you will be prompted to check your email for a login code. Do so and enter the code to create a new account.
Upon signing up, you should have access to the course content, including this installfest! Continue on from here in the app.
🚨 Don't have access to the course content? Let your instructor know immediately so that you can complete the installfest and have access to the course content.
We will be using slack to communicate throughout the course. You will receive an invite to the relevant channels via email. You can log in via the web browser, but downloading / installing the app is highly recommended. Download Slack here and install it.
If you haven't already, download the Zoom client and install it.
From Microsoft:
Microsoft PowerToys is a set of utilities for power users to tune and streamline their Windows experience for greater productivity. Inspired by the Windows 95 era PowerToys project, this reboot provides power users with ways to squeeze more efficiency out of the Windows 10 shell and customize it for individual workflows.
Among its many useful tools, PowerToys includes one of the best window managers: FancyZones - which allows you to customize window layouts and get the best setup just for you.
Get PowerToys here.
When possible, please copy the commands from this page. You will use most of the commands here once and never again. Typing them out will only introduce the possibility for you to make errors. Certain commands will require you to alter portions of them - this is specifically called out when they appear. There are no bonus points for doing work that has already been done for you.
Use Windows Logo Key + R on your keyboard, type powershell, and use Ctrl + Shift + Enter on your keyboard to run as administrator.
PowerShell running with administrative access. Note the title bar!
Use this command to enable the Windows Subsystem for Linux:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestartUse this command to enable the Virtual Machine Platform:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestartSave any work you want to keep, including this page.
Restart your computer to continue!
Use Windows Logo Key + r on your keyboard, type powershell, and use Ctrl + Shift + Enter on your keyboard to run as administrator.
Use this command to set WSL 2 as the default WSL version:
wsl --set-default-version 2Run the wsl --set-default-version 2 command again after the install is completed. The message should not appear.
Follow this link to Ubuntu 20.04 LTS on the Microsoft Store. Select the Get button which will launch the Microsoft Store application. Select the Get button again on the page inside the Microsoft Store application.
Ubuntu 20.04 LTS on the Microsoft Store
Ubuntu 20.04 LTS will install and can then be started by selecting the Launch button.
Ubuntu will then finalize the installation, which may take a few minutes. You will then be prompted to create a username and password. The password will not be visible as you type it. It is extremely important that you do not forget this username and password - preferably you will store it an a password manager such as Bitwarden or 1Password.
To re-launch Ubuntu 20.04 LTS press Windows Logo Key + r, enter ubuntu2004, and select OK
Windows does not manage your Linux installation and will not automatically perform updates. To manually do this use this command:
sudo apt update && sudo apt upgrade
Do this now. Enter your password when prompted, and accept changes to be made.
Also run this command to ensure you have wget (to retrieve content from web servers) and ca-certificates (to ensure SSL-based apps can check the authenticity of the connections they make):
sudo apt-get install wget ca-certificatesYou may get notifications that these are already installed. If so, great.
zsh is the shell of taste and class. Install it with this command:
sudo apt install zshVerify the installation with this command:
zsh --versionThe version number should be 5.4.2 or greater
Make zsh the default shell with this command. Enter your Linux password when prompted.
chsh -s $(which zsh)Close Ubuntu with this command:
logoutLaunch Ubuntu again by pressing Windows Logo Key + r on your keyboard, entering ubuntu2004, and selecting OK.
Ubuntu will launch and likely present you with this screen:
The zsh-newuser-install function running. Enter 2 for a default configuration.
Your terminal likely looks different now!
zsh in action
but to confirm it worked we can use this command:
echo $SHELLThis should return /usr/bin/zsh.
Finally, just to be extra sure use this command:
$SHELL --versionThis should return the same version number as the zsh --version command you ran earlier.
We're also going to install Oh My Zsh - an "open-source, community-driven framework for managing your zsh configuration." Use this command:
sh -c "$(wget https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh -O -)"
The result!
The vanilla configuration of Oh My Zsh is great for our needs, but you can further customize it if you want to - check out their website and their documentation to see how.
If you have not installed Visual Studio Code from the Visual Studio Code site do so now. Install Visual Studio Code on Windows - not in the WSL file system.
❗ When prompted to `Select Additional Tasks` during installation, be sure to check the `Add to PATH` option so you can easily open a folder in WSL using the `code` command.Once VS Code is installed continue by Installing the Remote - WSL extension in Visual Studio Code.
Microsoft has this to say about running extensions on WSL:
The Remote-WSL extension splits VS Code into a “client-server” architecture, with the client (the user interface) running on your Windows machine and the server (your code, Git, plugins, etc) running remotely.
When running VS Code Remote, selecting the 'Extensions' tab will display a list of extensions split between your local machine and your WSL distribution.
Installing a local extension, like a theme, only needs to be installed once.
Some extensions, like the Python extension or anything that handles things like linting or debugging, must be installed separately on each remote WSL distribution. VS Code will display a warning icon ⚠, along with a green "Install in WSL" button, if you have an extension locally installed that is not installed on your WSL Remote.
❗ This concept is **VERY IMPORTANT.** You are now running two separate operating systems simultaneously on your machine. When something is installed in one operating system, the other will not know about it! Let's explore this concept more.
If you don't already have Git installed in Windows 10 do that now from here.
💡 While you could use git on Windows as a source control manager, we won't be for our purposes - instead we will be using it mainly for it's credential management features. Unless you have a specific need for the features unchecked it's recommended you use only install the checked components below:Do not change the install location.
You will be given many prompts on features to install and choices to make while installing Git. All of these may be left as their default, except for the ones below.
Note we have unchecked some features not required for our purposes that may only be confusing or get in the way.
When prompted, you should select Use Visual Studio Code as Git's default editor.
.png)
Also ensure that you are using Git Credential Manager Core
.png)
Use the Git Credential Manager Core
All other settings may be left as their default.
Git comes pre-installed with Ubuntu, but ensure you have the most recent stable version with:
sudo add-apt-repository ppa:git-core/ppaWhen prompted, press Enter
Then enter:
sudo apt-get updateand
sudo apt-get install gitAdd your GitHub username, email, and password to your git configuration:
git config --global user.name "Username"Replace Username with your name. Ensure you leave the quotes surrounding your username.
git config --global user.email "user@email.com"Replace user@email.com with the email address associated with your GitHub. Ensure you leave the quotes surrounding your email.
git config --global credential.helper "/mnt/c/Program\\ Files/Git/mingw64/libexec/git-core/git-credential-manager-core.exe"Now any git operation you perform within Ubuntu will use the credential manager.
As shown here you can use git config --global user.name to check your stored username and git config global user.email to check your stored email.
Set the default branch name to main with this command:
git config --global init.defaultBranch mainSet the default git editor to VS Code with this command:
git config --global core.editor "code --wait"and finally turn off rebasing as the default behavior when making a pull:
git config --global pull.rebase falseProper code, utilities, and the use of Git ignore files prevent us from uploading private secrets to the public internet.
A global Git ignore file will prevent us from uploading private secrets to the public internet across all of your projects so that you don't have to worry about making the appropriate entries in every project's Git ignore.
Return to Ubuntu and use this command to create a .gitignore_global file in the user directory:
touch ~/.gitignore_globalNext, configure Git to use this file:
git config --global core.excludesfile ~/.gitignore_globalOpen the new .gitignore_global file in VS Code:
code ~/.gitignore_global
Creating and opening ~/.gitignore_global in VS Code
The new .gitignore_global file open in VS Code. Note the WSL: Ubuntu-20.04 icon in the lower left corner.
Here is a .gitignore_global file for you to use.
Open the above page and copy all of its contents.
Paste the contents of the file you copied into VS Code.
The end of the new .gitignore_global file.
This should save the file but make sure it gets saved by also manually saving, either by using Save in the File Menu or by pressing Ctrl + s.
You can close VS Code for now.
Auto Save with a check next to the option, indicating that it is turned on.
Github provides a way to host Git repos in the cloud. It enables collaboration and is wildly popular. If you have not already created an account there, do so now.
We'll be using the GitHub command line utility to perform some actions on GitHub as well. Install it with this command:
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key C99B11DEB97541F0
sudo apt-add-repository https://cli.github.com/packages
sudo apt update
sudo apt install ghThen login with this command:
gh auth loginYou will be prompted to login to a github.com account or a GitHub Enterprise account. Select the github.com option. A second prompt will appear asking how you would like to authenticate. Select the Login with a web browser option.
You will then be prompted to copy the one time code from the terminal. Do this now. Then press the Enter key to open the github.com login page in your browser.
Complete the login process, authorize the GitHub CLI, and return to your terminal. If you were successful, you will receive a message that says authentication is complete. Press Enter.
The final prompt will ask you to choose whether you want to use HTTPS or SSH. Select the HTTPS option.
The gh auth login process.
GitHub is deprecating the use of password authentication via the command line starting on August 13, 2021, as detailed in this GitHub blog post. To prepare for this change, we will be authenticating using GitHub's preferred authentication method: Personal Access Tokens (PATs).
First, visit https://github.com and ensure that you are signed in. Also, ensure that you have verified your email address with GitHub. After doing so, navigate to https://github.com/settings/tokens.
On the Personal access tokens page, click Generate new token.
The Personal access tokens page in Developer Settings. The Generate new token button is highlighted.
You will be taken to a page prompting you to create a new personal access token. Fill the Note field with the name of the device you are using the token with. Select all the repo scopes - ensure your selections match what is in the screenshot below. When you have done so, click the Generate token button.
You will be taken back to the Personal access tokens page, and the token you just created will be visible:
Click the clipboard button to copy the newly created token.
🚨 You will only see the token on this page ***ONCE***. You ***MUST*** copy it now and paste it in a secure and private place (preferably in a password manager). Treat this PAT as you would a password! The PAT will be used in place of a password to interact will GitHub on the command line! 🧠 Using multiple machines? It is best practice to create a new PAT for each device requiring command-line access to GitHub - this way, if you need to revoke access to any single device, none of your other devices are impacted.Place the token in a secure place!
🚨 Although all the files you have stored in Windows are available on the Ubuntu side in `/mnt/c`, accessing them comes at a significant performance cost. Therefore the code you write will be stored in the Ubuntu storage space. 💡 The Ubuntu storage space can be accessed from Windows at: `\\wsl$\Ubuntu-20.04\`.You shouldn't really have to bring files from Windows to Ubuntu or from Ubuntu to Windows often, but if you see this being an issue, you can use a service like Dropbox to help manage this work for you. As a bonus you'll be able to easily bring files into Ubuntu from other machines and visa-versa as well.
Optional: Follow the Dropbox Headless Install via command line instructions found here.
Head to the Microsoft Store app again and get, then Install Windows Terminal.
Now when you want to interact directly with Ubuntu you can do so from within the Windows Terminal.
Launch Windows Terminal. It will initially launch with only a Windows PowerShell tab but you can add a Ubuntu 20.04 LTS tab with the dropdown arrow in the title bar.
Select Ubuntu-20.04 to start an Ubuntu terminal session.
Your session may start in the Windows home directory. If this is the case press ctrl + , on your keyboard to launch the Windows Terminal settings (or access settings from the drop down menu).
Find the Ubuntu-20.04 profile. Add a comma to the end of the last line and add a new line with this content:
"commandline" : "wsl.exe ~"
The profiles list with the new line added to the Ubuntu-20.04 profile
You can also make the default profile the Ubuntu-20.04 profile by copying the guid of the Ubuntu profile ({07b52e3e-de2c-5db4-bd2d-ba144ed6c273} above, but yours will be different) and replace the existing defaultProfile.
{07b52e3e-de2c-5db4-bd2d-ba144ed6c273} is now the default profile
As of February 5, 2021 multiple default profiles cannot be specified here, but it is an active feature request with broad support here.
If you don't have it open already, launch the Windows Terminal and pin it to your task bar. From now on you will launch Ubuntu from here.
Use this command to install nvm which we will use to install node:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bashThe enter this command block, which will append the nvm directory to your ~/.zshrc file:
cat << EOF >> ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
EOFAfter doing so, restart the terminal session, and run the nvm --version command once more. If you still do not get a version number, alert your instructor.
Restart the terminal session.
Use nvm to install node with this command:
nvm install nodeWith node installed install nodemon globally with this command:
npm i -g nodemonDevelopers avoid using the mouse whenever possible because they are more productive when their hands are on the keyboard. Windows lets us do this by opening applications using Search instead of the mouse by:
- Pressing
Windows Keyto open Search - Start typing the name of the app until the app is highlighted
- Press
Enterto open the app!
Quickly switch between running applications by pressing Alt + Tab.
You'll periodically need to take screenshots. Use Windows Key + Shift + s to take a screenshot of an area of your screen. If you have it you can also use Prt Sc to take a screenshot of your entire screen.
The screenshot you take will be placed on your clipboard, and you can paste it wherever you would like to use it.
Uploading Screenshots and Images to imgur
Often you will need to share images with others or use them in your applications, notes, readme files, etc. Unfortunately, if an image exists only on your computer, you lose the ability to use it anywhere but on your computer. To get around this, we can upload images to a cloud service like imgur, one of the most popular image hosting services on the internet.
Feel free to open an account there, so you can keep track of what you upload, but you can also use their service without an account.
You now are set up to start developing in Linux on Windows! Be very proud of yourself, that was quite the process!
While this is optional, we recommend using a password manager to help keep track of the various accounts and logins you will be creating throughout the course and in the rest of your digital life. Bitwarden is free, open-source, and provides a great user experience, but if you're using a different one (or not using one at all), that is no problem.