--- tags: - linux - windows - wsl - installation - workflow --- # Windows to Linux Setup Workflow This comprehensive guide outlines the safe and optimized workflow for installing Linux (via WSL2) on a Windows machine. It leverages our custom auditing and configuration scripts to ensure a stable development environment. ## 1. Pre-Installation Audit Before making any changes, we must identify the capabilities of the host Windows operating system. * **Objective:** Confirm that the system supports `Microsoft-Windows-Subsystem-Linux` and `VirtualMachinePlatform`. * **Tool:** [[../Windows-Features|Windows Feature Auditor]] * **Action:** Run the script and check for "Unsupported" flags (Red). If features are "Disabled" (Yellow), they will be handled in Step 3. ## 2. System State Backup Modifying boot-level virtualization features involves Registry changes. It is critical to save a snapshot of the current configuration. * **Objective:** Create a restore point for developer settings. * **Tool:** [[../Backup-DevSettings|Backup Dev Settings]] * **Action:** Execute the script to generate a timestamped `.reg` file in your backup directory. ## 3. Host Environment Optimization We need to prepare the "Garage" (Windows) to house the "Car" (Linux). This involves enabling the Hypervisor and adjusting file system policies. * **Objective:** Enable WSL, VM Platform, Developer Mode, and Long Paths. * **Tool:** [[../Set-DevOptimized|Set Dev Optimized]] * **Action:** Run the script. * **Critical:** You must **Restart your Computer** after this script completes to finalize the Hypervisor installation. ## 4. Linux Distribution Deployment Once the system has rebooted and the virtualization layer is active, you can install the operating system. * **Command:** Open PowerShell (Admin) and run: ```powershell wsl --install ``` * **Details:** This downloads the Ubuntu distribution and the Linux Kernel. * **Post-Install:** A new window will open prompting you to create a UNIX username and password. ## 5. Windows Terminal Customization For the best experience, configure **Windows Terminal** to prioritize your new Linux environment. * **Set as Default Profile:** 1. Open Windows Terminal and press `Ctrl + ,` to open Settings. 2. Under **Startup**, set "Default profile" to **Ubuntu**. * **Start in Linux Home:** 1. Select the **Ubuntu** profile from the sidebar. 2. In **General > Starting directory**, uncheck "Use parent process directory". 3. Enter: `\\wsl$\Ubuntu\home\your-username` (replace `your-username` with your UNIX name). ## 6. Accessing Linux Files from Windows WSL makes it seamless to move files between your Windows and Linux environments. * **From Windows Explorer:** 1. Open File Explorer. 2. In the address bar, type `\\wsl.localhost\` (or the older `\\wsl$\`) and press Enter. 3. You will see a folder for your distribution (e.g., `Ubuntu`), which you can browse like any other Windows folder. * **From the Linux Terminal:** 1. Navigate to any directory within your Linux environment (e.g., `cd ~`). 2. Type `explorer.exe .` and press Enter. A Windows File Explorer window will open directly to that location. ## 7. Post-Installation Configuration With Linux installed and accessible, the next step is to prepare the internal environment for development. * **Objective:** Update system packages and install core tools (Git, Curl, Compilers). * **Guide:** [[Post-Install-Config|Post-Install Linux Configuration]] * **Action:** Follow the linked guide to bring your new Ubuntu system up to date. ## 8. Node.js Development Setup For JavaScript and TypeScript developers, we use `nvm` (Node Version Manager) to handle multiple Node.js versions without permission issues. * **Objective:** Install `nvm` and the latest LTS version of Node.js. * **Guide:** [[NodeJS-Dev-Setup|Setting up a Node.js Development Environment]] * **Action:** Follow the guide to configure your JavaScript runtime. ## 9. Python Development Setup To manage multiple Python versions and create isolated project environments, we use a combination of `pyenv` and `venv`. * **Objective:** Install `pyenv` to manage Python versions and use `venv` for project-specific dependencies. * **Guide:** [[Python-Dev-Setup|Setting up a Python Development Environment]] * **Action:** Follow the linked guide to install and configure your Python toolchain. ## 10. Docker Setup With the Linux environment fully configured, you can now install Docker to run containerized applications. This allows you to deploy software and its dependencies in isolated packages that run identically everywhere. * **Objective:** Install the Docker Engine and Docker Compose plugin. * **Guide:** [[Ubuntu-Docker-Setup|Setting up Docker on Ubuntu]] * **Action:** Follow the guide to install Docker from its official repository. ## 11. VS Code Remote Development Visual Studio Code's most powerful feature is its ability to run on Windows while executing code and using tools inside your Linux environment. This provides a seamless development experience, combining the best of both operating systems. * **Objective:** Connect VS Code to your WSL instance to edit, debug, and run code directly within Linux. * **Action:** Install the official WSL extension and open a project from your Linux terminal. ### Setup Steps: 1. **Install the WSL Extension:** * Open VS Code on Windows. * Go to the **Extensions** view (`Ctrl+Shift+X`). * Search for `WSL` by Microsoft and click **Install**. 2. **Open a Project:** * Open your **Ubuntu terminal** (not PowerShell). * Navigate to a project directory (e.g., `cd ~/my-project`). * Type the command: ```bash code . ``` * The first time you run this, it will download a small "VS Code Server" into your Linux environment. Afterwards, it will open the folder directly in VS Code, with the terminal and all tools running inside WSL. ## 12. Sharing SSH Keys (Windows to WSL) If you already have SSH keys generated on Windows (e.g., for GitHub or remote servers), you don't need to generate new ones. You can copy them securely into your Linux environment. * **Objective:** Import existing Windows SSH keys into WSL. * **Action:** Copy keys and set strict permissions. ### Steps: 1. **Open your Ubuntu terminal.** 2. **Copy the keys:** ```bash cp -r /mnt/c/Users/your-windows-username/.ssh ~/ ``` *(Replace `your-windows-username` with your actual Windows folder name).* 3. **Fix Permissions:** Linux is very strict about key security. ```bash chmod 700 ~/.ssh chmod 600 ~/.ssh/id_rsa chmod 644 ~/.ssh/id_rsa.pub ``` ## 13. Backing Up Your Linux Environment Once you have configured your perfect development environment, you should create a full backup. This allows you to restore your exact setup on another machine or recover from a critical error. * **Objective:** Export the entire Linux filesystem to a portable file. * **Action:** Use the native export command. ### Steps: 1. **Open PowerShell** (on Windows). 2. **Export the Distro:** ```powershell wsl --export Ubuntu "D:\backups\ubuntu-backup.tar" ``` *(Replace `D:\backups\` with your external drive location).* 3. **To Restore:** ```powershell wsl --import Ubuntu "C:\WSL\Ubuntu" "D:\backups\ubuntu-backup.tar" ``` ## 14. Reversion & Cleanup If you need to uninstall Linux and return Windows to its stock configuration (e.g., to free up resources or reset the environment). * **Objective:** Disable WSL, Hyper-V components, and Developer Mode. * **Tool:** [[../Reset-DevDefaults|Reset Dev Defaults]] * **Action:** Run the script and reboot to clear the virtualization features from memory. ## 15. Troubleshooting Common issues encountered during the setup process and their solutions. * **Error 0x80370102 (Virtualization not enabled):** * **Cause:** Virtualization Technology (VTx/SVM) is disabled in your computer's BIOS/UEFI. * **Fix:** Reboot your computer, enter BIOS (usually F2, F10, or Del), and enable "Intel Virtualization Technology" or "SVM Mode". * **Error 0x800701bc (WSL 2 requires an update):** * **Cause:** The Linux kernel package is outdated or missing. * **Fix:** Run `wsl --update` in PowerShell (Admin). * **"The requested operation requires elevation":** * **Cause:** You are running the terminal as a standard user. * **Fix:** Right-click PowerShell or your script and select "Run as Administrator".