{"id":14063159,"url":"https://github.com/rse/unix-under-windows","last_synced_at":"2025-04-19T09:58:33.817Z","repository":{"id":66345645,"uuid":"183823501","full_name":"rse/unix-under-windows","owner":"rse","description":"Unix Environment under Windows","archived":false,"fork":false,"pushed_at":"2024-09-14T21:06:41.000Z","size":843,"stargazers_count":34,"open_issues_count":1,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-15T21:55:49.933Z","etag":null,"topics":["docker","dotfiles","environment","mintty","ubuntu","unix","windows","wsl"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-27T21:32:13.000Z","updated_at":"2024-10-30T01:29:30.000Z","dependencies_parsed_at":"2024-08-13T07:14:14.876Z","dependency_job_id":null,"html_url":"https://github.com/rse/unix-under-windows","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Funix-under-windows","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Funix-under-windows/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Funix-under-windows/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Funix-under-windows/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rse","download_url":"https://codeload.github.com/rse/unix-under-windows/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249669907,"owners_count":21308668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","dotfiles","environment","mintty","ubuntu","unix","windows","wsl"],"created_at":"2024-08-13T07:03:06.040Z","updated_at":"2025-04-19T09:58:33.800Z","avatar_url":"https://github.com/rse.png","language":null,"funding_links":[],"categories":["Others"],"sub_categories":[],"readme":"\u003cimg src=\"https://assets.ubuntu.com/v1/29985a98-ubuntu-logo32.png\" width=\"120\" align=\"right\" alt=\"\"/\u003e\n\u003cimg src=\"https://upload.wikimedia.org/wikipedia/commons/5/5f/Windows_logo_-_2012.svg\" width=\"120\" align=\"right\" alt=\"\"/\u003e\n\nAuthor: [Dr. Ralf S. Engelschall](mailto:rse@engelschall.com)\u003cbr/\u003e\nVersion: 2.4.5 (2024-07-20)\n\n# Unix Environment under Windows\n\nThis is a documentation on how to setup a reasonable but opinionated Unix development environment under\n[*Microsoft Windows 10/11*](https://windows.com) (Pro edition, 64-bit mode, version \u0026ge; 1809) with the help of the\nnative [*Windows Subsystem for Linux (WSL)*](https://devblogs.microsoft.com/commandline/),\nthe [*Ubuntu*](https://www.ubuntu.com/) GNU/Linux distribution,\nDr. Ralf S. Engelschall's [*Unix dotfiles*](https://github.com/rse/dotfiles) shell environment,\nthe terminal emulator [*MinTTY/WSLTTY*](https://github.com/mintty/wsltty) and\nthe [*Docker Desktop for Windows*](https://www.docker.com/products/docker-desktop)\ncontainer execution platform.\n\n![screenshot](screenshot.png)\n\n\u003e Notice: In short, the crux of this setup in contrast to the usual standard WSL setups is:\n\u003e\n\u003e - convenient root access (password-less `sudo`)\n\u003e - reasonably mapped home directory (`/c/Users/$USER`)\n\u003e - essential Unix shell configurations for Bash, Vim, Vifm, TMux and Git (\"dot-files\")\n\u003e - essential Unix shell tools (OpenSSH, RSYNC, etc)\n\u003e - additional WSL shell tools (`wsl-open`)\n\u003e - improved host terminal emulator (MinTTY/WSLTTY)\n\u003e - host SSH agent with transparent access from within WSL (`weasel-pageant`)\n\u003e - Docker and Kubernetes client CLIs\n\u003e - optionally, Docker runtimes inside WSL (DockerD, Podman) or on host (Docker for Windows)\n\u003e - optionally, essential programming language runtime (JavaScript/Java)\n\n## Install Windows Subsystem for Linux (WSL)\n\n1. **Ensure Windows 10/11 Professional/Enterprise, 64 Bit, Version \u0026ge; 18.09**:\u003cbr/\u003e\n   Ensure you are running at least Windows 10 Professional or Windows 10\n   Enterprise in 64-bit mode and in Version 1809 (October 2018), 1903\n   (April 2019), 1909 (November 2019) or newer (including Windows 11).\n\n   \u003e Rationale: Windows Subsystem for Linux (WSL) is available only\n   \u003e under those Windows editions, only under 64-bit and in a reasonable\n   \u003e fashion only under at least this version or newer.\n   \u003e Windows 10 in Version 1809 is the bare minimum. The recommended\n   \u003e system is at least Windows 10 in Version 1909 or newer (including Windows 11).\n\n   - *START* \u0026rarr; *Settings* \u0026rarr; *System* \u0026rarr; *About*:\n   - ... *Device Specifications* \u0026rarr; *System type*\n   - ... *Windows Specifications* \u0026rarr; *Edition*\n   - ... *Windows Specifications* \u0026rarr; *Version*\n\n   Notice:\n\n   \u003e If you have a different edition or you are running in 32-bit mode,\n   \u003e you are out of luck with WSL. Sorry, then you have to went with\n   \u003e [MSYS2](https://www.msys2.org/) or [Cygwin](https://www.cygwin.com/).\n   \u003e If you want to perform a fresh Windows 10/11 installation, start over with Microsoft's\n   \u003e [Download Windows 10 Disc Image (ISO File)](https://www.microsoft.com/en-us/software-download/windows10ISO/)\n   \u003e or [Download Windows 11 Disc Image (ISO File)](https://www.microsoft.com/software-download/windows11).\n   \u003e If you just still have an older Windows version, upgrade with one of the following\n   \u003e options:\n   \u003e\n   \u003e - Windows Updates: *START* \u0026rarr; `windows update settings` \u003ckbd\u003eRETURN\u003c/kbd\u003e\n   \u003e - Windows Upgrades: [Windows 10 Update Assistant](https://www.microsoft.com/software-download/windows10)\n   \u003e - Windows Upgrades: [Windows 11 Update Assistant](https://www.microsoft.com/software-download/windows10)\n\n2. **Enable Windows Subsystem for Linux**:\u003cbr/\u003e\n   Enable the Windows feature *Windows Subsystem for Linux*.\n   A reboot might be necessary.\n\n   \u003e Rationale: Windows Subsystem for Linux is the core feature we want to use.\n\n   - *START* \u0026rarr; `powershell` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Run as administrator*\n   - `Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux`\n\n   Alternatively:\n\n   - *START* \u0026rarr; `cmd` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Run as administrator*\n   - `dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart`\n\n   Alternatively:\n\n   - *START* \u0026rarr; `control panel` \u0026rarr; *Programs* \u0026rarr; *Programs and Features*\n     \u0026rarr; *Turn Windows features on or off* \u0026rarr; *Windows-Subsystem for Linux*\n\n   \u003e Notice: In case you have trouble to enable *Windows Subsystem for Linux*, this can have many reasons.\n   \u003e In most cases, the reason is that point (1) above is not exactly fulfilled. Start over there again.\n\n3. **Enable \"Virtual Machine Platform\" Feature**\u003cbr/\u003e\n   Enable the Windows feature *Virtual Machine Platform* (required for WSL2).\n   A reboot might be necessary.\n\n   \u003e Rationale: WSL2 is recommended.\n\n   - *START* \u0026rarr; `powershell` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Run as administrator*\n   - `Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform`\n\n   Alternatively:\n\n   - *START* \u0026rarr; `cmd` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Run as administrator*\n   - `dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart`\n\n   Alternatively:\n\n   - *START* \u0026rarr; `control panel` \u0026rarr; *Programs* \u0026rarr; *Programs and Features*\n     \u0026rarr; *Turn Windows features on or off* \u0026rarr; *Virtual Machine Platform*\n\n4. **Install/Update WSL2 Linux Kernel**\u003cbr/\u003e\n   Update the WSL2 Linux kernel.\n\n   \u003e Rationale: WSL2 Linux kernel has to be up-to-date or WSL2 will complain.\n\n   - Visit the Microsoft [WSL2 Information Page](https://aka.ms/wsl2kernel)\n     and [download and run the MSI installer](https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi)\n     for the WSL 2 Linux Kernel.\n\n5. **Enable Hardware Virtualization**\u003cbr/\u003e\n   Enable the CPU Hardware Virtualization in the PC BIOS (required for WSL2).\n\n   - Reboot your system\n   - Hold \"DELETE\" key during boot.\n   - Enable CPU Hardware Virtualization (VT-x/VMX).\n\n6. **Update WSL**:\u003cbr/\u003e\n   Update to the latest version of *Windows Subsystem for Linux*.\n\n   - *START* \u0026rarr; `powershell` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Run as administrator*\n   - `wsl.exe --update`\n\n## Install Ubuntu GNU/Linux Operating System\n\n1. **Install Ubuntu 24.04 LTS**:\u003cbr/\u003e\n   Install Ubuntu GNU/Linux 24.04 Long Term Support (LTS) from the Microsoft Store.\n\n   \u003e Rationale: you need a reasonable GNU/Linux distribution and it should receive updates for a longer time.\n\n   - *START* \u0026rarr; `microsoft store` \u0026rarr; *Search* \u0026rarr; `ubuntu 24.04 lts` \u0026rarr; *Install*\n\n   \u003e Notice: In case the Microsoft Store is not available on your system, the reason\n   \u003e can be that you still have User Account Control (UAC) disabled, or\n   \u003e you are still not signed in with a Microsoft Account (although it\n   \u003e should be not required), or your Windows is still not activated or\n   \u003e you are still running an evaluation version of Windows. Anyway, try\n   \u003e to fix the problems the following way:\n   \u003e \n   \u003e - *START* \u0026rarr; *Settings* \u0026rarr; *Updates \u0026 Security* \u0026rarr; *Troubleshoot* \u0026rarr; *Windows Store Apps* \u0026rarr; *Run the troubleshooter*\n\n## Setup Ubuntu GNU/Linux Operating System\n\n1. **Enter Ubuntu under WSL**:\u003cbr/\u003e\n   Enter Ubuntu GNU/Linux under Windows Subsystem for Linux.\n\n   \u003e Rationale: we have to setup Ubuntu from itself.\n\n    - *START* \u0026rarr; *Ubuntu 24.04*\n\n   Just be patient on first launch, it really takes time.\n   Then, when asked for your username, enter the same as your Windows username.\n   When asked for your password, enter either your Windows password or another one, but\n   remember it (at least once until the step where we configure sudo(8) below)!\n   For all other questions, keep the defaults.\n\n2. **Enable Convenient Root Access**:\u003cbr/\u003e\n   Ensure no password is needed for subsequent root access.\n\n   \u003e Rationale: just convenience only -- feel free to ignore if you want to enter your password over and over again.\n\n    - `sudo vi /etc/sudoers`\u003cbr/\u003e\n      \u0026larr; `%sudo ALL=(ALL:ALL) ALL`\u003cbr/\u003e\n      \u0026rarr; `%sudo ALL=(ALL:ALL) NOPASSWD: ALL`\n\n3. **Upgrade Ubuntu Operating System**:\u003cbr/\u003e\n   Upgrade to the latest package versions of Ubuntu and allow APT to use HTTPS.\n\n   \u003e Rationale: you always want the latest updates and Docker later needs HTTPS access.\n\n   - `sudo apt update -y \u0026\u0026`\u003cbr/\u003e\n     `sudo apt upgrade -y --with-new-pkgs \u0026\u0026`\u003cbr/\u003e\n     `sudo apt install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common`\n\n4. **Mount Windows directories in WSL with Meta-Data enabled**:\u003cbr/\u003e\n   Configure the mounting of Windows directories in WSL (`/c` instead of `/mnt/c`) and with *Meta-Data* enabled.\n\n   \u003e Rationale: allow POSIX file permissions on Windows drives from within WSL.\n\n    - `sudo vi /etc/wsl.conf`\u003cbr/\u003e\n      \u0026rarr; `[boot]`\u003cbr/\u003e\n      \u0026rarr; `systemd = true`\u003cbr/\u003e\n      \u0026rarr; `[automount]`\u003cbr/\u003e\n      \u0026rarr; `enabled = true`\u003cbr/\u003e\n      \u0026rarr; `root    = /`\u003cbr/\u003e\n      \u0026rarr; `options = \"metadata,umask=022\"`\n\n5. **Use Combined Home Directory**:\u003cbr/\u003e\n   Map the Unix home directory to the regular Windows home directory.\n\n   \u003e Rationale: just convenience only -- feel free to ignore.\n\n   - *START* \u0026rarr; `cmd`\n   - `wsl --shutdown`\n   - `wsl -u root usermod -d /c/Users/%USERNAME% %USERNAME%`\n\n6. **Activate Filesystem Layout**:\u003cbr/\u003e\n   Perform a logout/login cycle on the host system to\n   activate the new filesystem layout (mapping of /c and home directory)\n\n   \u003e Rationale: WSL does not re-mount the filesystem without a logout/login or reboot\n\n## Configure Unix Shell Environment\n\n1. **Re-Enter Ubuntu under WSL**:\u003cbr/\u003e\n   Re-Enter Ubuntu GNU/Linux under Windows Subsystem for Linux again.\n\n   \u003e Rationale: we have to configure the Unix environment from itself.\n\n    - *START* \u0026rarr; *Ubuntu 24.04*\n\n2. **Install Essential Unix Tools**:\u003cbr/\u003e\n   Install all necessary essential and some more useful Unix tools.\n\n   \u003e Rationale: the subsequent Unix Shell Configurations are partially based on them and you really want a decent Unix environment.\n\n   First, install the tools which available via standard package manager:\n\n   - `sudo apt install -y bash less vim vifm tmux \u0026\u0026 `\u003cbr/\u003e\n     `sudo apt install -y procps lsof dnsutils tcpdump \u0026\u0026 `\u003cbr/\u003e\n     `sudo apt install -y openssh-client stunnel subversion git curl \u0026\u0026 `\u003cbr/\u003e\n     `sudo apt install -y mc tree file findutils \u0026\u0026 `\u003cbr/\u003e\n     `sudo apt install -y rsync rdup rclone restic w3m lftp \u0026\u0026 `\u003cbr/\u003e\n     `sudo apt install -y atool gzip bzip2 xz-utils zip unzip \u0026\u0026 `\u003cbr/\u003e\n     `sudo apt install -y diffutils diffstat patch patchutils par \u0026\u0026 `\u003cbr/\u003e\n     `sudo apt install -y openssl gnupg golang-cfssl apg uuid bc \u0026\u0026 `\u003cbr/\u003e\n     `sudo apt install -y imagemagick ghostscript poppler-utils \u0026\u0026 `\u003cbr/\u003e\n     `sudo apt install -y gcc g++ bison flex`\n\n   Second, install the tool [FZF](https://github.com/junegunn/fzf) which is not available\n   (at least not in latest version) via standard package manager:\n\n   - `curl -skLO https://github.com/junegunn/fzf/releases/download/v0.54.1/fzf-0.54.1-linux_amd64.tar.gz \u0026\u0026 `\u003cbr/\u003e\n     `tar zxf fzf-*-linux_amd64.tar.gz \u0026\u0026 `\u003cbr/\u003e\n     `sudo install -c -m 755 fzf /usr/local/bin/ \u0026\u0026 `\u003cbr/\u003e\n     `rm fzf fzf-*-linux_amd64.tar.gz`\n\n3. **Optionally Install Additional Unix Tools**:\u003cbr/\u003e\n   Install additionally useful Unix tools.\n\n   \u003e Rationale: Git-Town and TTY2Web are often useful.\n\n   - `curl -skLO https://github.com/git-town/git-town/releases/download/v14.3.1/git-town_linux_intel_64.deb \u0026\u0026 `\u003cbr/\u003e\n     `sudo dpkg -i git-town_*.deb \u0026\u0026 `\u003cbr/\u003e\n     `rm git-town_*.deb \u0026\u0026 `\u003cbr/\u003e\n     `curl -skLO https://github.com/kost/tty2web/releases/download/v3.0.3/tty2web_linux_amd64 \u0026\u0026 `\u003cbr/\u003e\n     `sudo install -c -m 755 tty2web* /usr/local/bin/tty2web \u0026\u0026 `\u003cbr/\u003e\n     `rm tty2web*`\n\n4. **Install Unix Shell Configurations**:\u003cbr/\u003e\n   Install Dr. Ralf S. Engelschall's essential Unix dotfiles.\n\n   \u003e Rationale: you really want a reasonable pre-configured Unix shell environment.\n\n   - `sudo apt install -y make \u0026\u0026 `\u003cbr/\u003e\n     `curl -skLO https://github.com/rse/dotfiles/archive/master.zip \u0026\u0026 `\u003cbr/\u003e\n     `unzip -x master.zip \u0026\u0026 `\u003cbr/\u003e\n     `(cd dotfiles-master \u0026\u0026 sudo make install) \u0026\u0026 `\u003cbr/\u003e\n     `rm -rf dotfiles-master \u0026\u0026 `\u003cbr/\u003e\n     `rm master.zip \u0026\u0026 `\u003cbr/\u003e\n     `dotfiles -f ~`\n\n5. **Install UTF-8 locale information**:\u003cbr/\u003e\n   Install the UTF-8 locale information into the system.\n\n   \u003e Rationale: prevent Bash from complaining afterwards.\n\n   - `sudo localedef -i en_US -f UTF-8 en_US.UTF-8`\n\n6. **Install Unix Shell Addon Configurations**:\u003cbr/\u003e\n   Install Dr. Ralf S. Engelschall's Bash-FZF and Bash-ENVRC addons.\n\n   \u003e Rationale: you really want a reasonable pre-configured Unix shell environment.\n   \u003e This especially includes an improved \u003ckbd\u003eCTRL+r\u003c/kbd\u003e functionality in Bash, which then opens\n   \u003e an FZF-based search functionality (which you can see in the screenshot above, too).\n\n   - `curl -skL https://raw.githubusercontent.com/rse/bash-fzf/master/bash-fzf.rc -o ~/.bash-fzf.rc \u0026\u0026 `\u003cbr/\u003e\n     `curl -skL https://raw.githubusercontent.com/rse/bash-envrc/master/bash-envrc.rc -o ~/.bash-envrc.rc \u0026\u0026 `\u003cbr/\u003e\n     `exec bash`\u003cbr/\u003e\n\n   - `cdpaths -g`\n\n7. **Optionally Extend Unix Shell Configurations**:\u003cbr/\u003e\n   Extend the Unix shell configuration with your personal information.\n\n   \u003e Rationale: these informations individualize your environment (replace the `\u003cxxx\u003e` placeholders, please).\n\n   - `vi ~/.dotfiles/gitconfig`\u003cbr/\u003e\n     \u0026rarr; `[user]`\u003cbr/\u003e\n     \u0026rarr; `user  = \u003cusername\u003e`\u003cbr/\u003e\n     \u0026rarr; `name  = \u003cfirstname\u003e \u003clastname\u003e`\u003cbr/\u003e\n     \u0026rarr; `email = \u003cfirstname\u003e.\u003clastname\u003e@\u003cdomain\u003e`\u003cbr/\u003e\n\n8. **Install WSL Utilities**:\u003cbr/\u003e\n   Install additional WSL utilities.\n\n   \u003e Rationale: you want additional features inside WSL.\n\n   - `sudo apt install -y ubuntu-wsl wslu \u0026\u0026 `\u003cbr/\u003e\n     `curl -skLO https://github.com/4U6U57/wsl-open/archive/master.zip \u0026\u0026 `\u003cbr/\u003e\n     `unzip -x master.zip \u0026\u0026 `\u003cbr/\u003e\n     `sudo install -c -m 755 wsl-open-master/wsl-open.sh /usr/local/bin/wsl-open \u0026\u0026 `\u003cbr/\u003e\n     `sudo mkdir -p /usr/local/share/man/man1 \u0026\u0026 `\u003cbr/\u003e\n     `sudo install -c -m 644 wsl-open-master/wsl-open.1 /usr/local/share/man/man1/ \u0026\u0026 `\u003cbr/\u003e\n     `rm -rf wsl-open-master \u0026\u0026 `\u003cbr/\u003e\n     `rm master.zip`\n\n   - `curl -skLO https://github.com/CzBiX/WSLHostPatcher/releases/download/v0.1.3/WSLHostPatcher.zip \u0026\u0026 `\u003cbr/\u003e\n     `unzip -x WSLHostPatcher.zip \u0026\u0026 `\u003cbr/\u003e\n     `mkdir -p ~/AppData/Local/WSLHostPatcher \u0026\u0026 `\u003cbr/\u003e\n     `chmod 755 WSLHostPatcher.exe \u0026\u0026 `\u003cbr/\u003e\n     `mv WSLHostPatch.dll WSLHostPatcher.exe ~/AppData/Local/WSLHostPatcher/ \u0026\u0026 `\u003cbr/\u003e\n     `rm -f WSLHostPatcher.zip WSLHostPatch*.*`\n\n   - `vi ~/.dotfiles/bashrc`\u003cbr/\u003e\n      \u0026rarr; `PATH=$PATH:/c/Windows/System32/WindowsPowerShell/v1.0/`\u003cbr/\u003e\n      \u0026rarr; `alias wsl=\"/c/Windows/System32/wsl.exe\"`\u003cbr/\u003e\n      \u0026rarr; `alias cmd=\"/c/Windows/System32/cmd.exe\"`\u003cbr/\u003e\n      \u0026rarr; `alias wsl-host-patcher=\"$HOME/AppData/Local/WSLHostPatcher/WSLHostPatcher.exe\"`\u003cbr/\u003e\n      \u0026rarr; `alias open=wsl-open`\n\n9. **Optionally avoid system messages**:\u003cbr/\u003e\n   Force the system to not display messages.\n\n   \u003e Rationale: you don't want to be nerved with those messages\n\n   - `touch ~/.hushlogin`\n\n## Install MinTTY/WSLTTY Terminal Emulator\n\n1. **Install MinTTY/WSLTTY**:\u003cbr/\u003e\n   Install the WSLTTY variant of MinTTY.\n\n   \u003e Rationale: a reasonable terminal emulator has to be used and the default WSL console is not good enough.\n\n   - [WSLTTY version \u0026ge; 3.7.1](https://github.com/mintty/wsltty/releases) \u0026rarr; `wsltty-*-install.exe`\n   - \u003ckbd\u003eWIN+r\u003c/kbd\u003e \u0026rarr; `%LOCALAPPDATA%\\wsltty` \u0026rarr; `add to context menu.lnk`\n\n2. **Install DejaVu Sans Mono font**:\u003cbr/\u003e\n   Install a perfect monospaced font for the terminal emulator.\n\n   \u003e Rationale: MinTTY/WSLTTY configuration below references it.\n\n   - download: [DejaVu Sans \u0026ge; 2.37](https://dejavu-fonts.github.io/Download.html) \u0026rarr; `dejavu-fonts-ttf-*.zip`\n   - extract: `dejavu-fonts-ttf-*.zip` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e *Extract all*\n   - install: `dejavu-fonts-ttf-*\\ttf\\` \u0026rarr; select all `*.ttf` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Install*\n\n3. **Install MinTTY/WSLTTY Configuration**:\u003cbr/\u003e\n   Install Dr. Ralf S. Engelschall's MinTTY/WSLTTY configuration.\n\n   \u003e Rationale: reasonable colors and fonts should be used in the terminal emulator.\n\n   - download: [MinTTY-config](https://github.com/rse/mintty-config/archive/master.zip)\n   - extract: `master.zip` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e *Extract all*\n   - copy: `mintty-config-master\\config`\n   - paste: `%APPDATA%\\wsltty` (override `config` file)\n\n4. **Optionally Make MinTTY/WSLTTY easily accessible**:\u003cbr/\u003e\n   Pin MinTTY/WSLTTY to the Windows taskbar and additionally assign it to the global Windows hotkey \u003ckbd\u003eCTRL+ALT+c\u003c/kbd\u003e.\n\n   \u003e Rationale: easy and quick access to the Unix shell\n\n   - *START* \u0026rarr; `wsl terminal` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e *Pin to taskbar*.\n   - Taskbar \u0026rarr; *WSL Terminal* \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *WSL Terminal* \u0026rarr;\u003cbr/\u003e\n   - ...\u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Properties* \u0026rarr; *Shortcut key* \u0026rarr; \u003ckbd\u003eCTRL+ALT+c\u003c/kbd\u003e.\n\n\u003chr/\u003e\n\n## Optionally Install Secure-Shell (SSH) Environment (feel free to skip)\n\n1. **Install PuTTY**:\u003cbr/\u003e\n   Install the PuTTY SSH client.\n\n   \u003e Rationale: you want to run the PuTTY Agent (`pageant`) for reasonable SSH agent support.\n\n   - [PuTTY Downloads](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) \u0026rarr; `putty-64bit-*-installer.msi`\n\n2. **Generate SSH Key**:\u003cbr/\u003e\n   Generate (or use existing) SSH key.\n\n   \u003e Rationale: you don't want to use passwords, of course.\n\n   - *START* \u0026rarr; `puttygen` \u003ckbd\u003eRETURN\u003c/kbd\u003e\n   - \u0026rarr; *Generate*\n   - \u0026rarr; *Key passphrase* \u0026amp; *Confirm passphrase*\n   - \u0026rarr; *Save public key* \u0026rarr; `c:\\Users\\\u003cusername\u003e\\Documents\\ssh-key-pub.pem`\n   - \u0026rarr; *Save private key* \u0026rarr; `c:\\Users\\\u003cusername\u003e\\Documents\\ssh-key-prv.ppk`\n   - \u0026rarr; *Conversions* \u0026rarr; *Export OpenSSH key* \u0026rarr; `c:\\Users\\\u003cusername\u003e\\Documents\\ssh-key-prv.pem`.\u003cbr/\u003e\n\n3. **Autostart PuTTY Agent**:\u003cbr/\u003e\n   Enable the PuTTY Agent to autostart on login and load the SSH private key.\n\n   \u003e Rationale: you want it to be running all the time.\n\n   - \u003ckbd\u003eWIN+e\u003c/kbd\u003e \u0026rarr; `%APPDATA%\\Microsoft\\Windows\\Start Menu\\Programs\\Startup` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *New* \u0026rarr; *Shortcut*\n   - `\"C:\\Program Files\\PuTTY\\pageant.exe\" \"C:\\Users\\\u003cusername\u003e\\Documents\\ssh-key-prv.ppk\"`\n\n5. **Install PuTTY Agent Client (Weasel-Pageant)**\u003cbr/\u003e\n   Install Weasel-Pageant for accessing the PuTTY Agent from within WSL.\n\n   \u003e Rationale: you want to directly access PuTTY Agent from within WSL.\n\n   - [Weasel-Pageant Downloads](https://github.com/vuori/weasel-pageant/releases) \u0026rarr; `weasel-pageant-1.4.zip`\n   - `weasel-pageant-1.4.zip` \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Extract all*\n   - move `weasel-pageant-1.4\\` to `%APPDATA%\\weasel-pageant\\`\n\n4. **Enter Ubuntu under WSL via MinTTY/WSLTTY**:\u003cbr/\u003e\n   Re-Enter Ubuntu GNU/Linux under Windows Subsystem for Linux again (this time via MinTTY/WSLTTY).\n\n   \u003e Rationale: we have to configure also the Unix version of SSH.\n\n    - *START* \u0026rarr; `wsl terminal` \u003ckbd\u003eRETURN\u003c/kbd\u003e\n\n5. **Configure Unix Environment for SSH Agent**:\u003cbr/\u003e\n   Configure the Unix environment to use the Weasel-Pageant as the SSH agent.\n\n   \u003e Rationale: in every WSL terminal you want SSH agent access available automatically.\n\n   - `vi ~/.dotfiles/bashrc`\u003cbr/\u003e\n     \u0026rarr; `eval $(~/AppData/Roaming/weasel-pageant/weasel-pageant -r -s)`\n\n## Optionally Enable Windows Subsystem for Linux (WSL) Version 2 (Windows 10/11 Version \u003e= 19.03 only) (feel free to skip)\n\n2. **Switch to use WSL 2**\n\n   - *START* \u0026rarr; `cmd`\n   - `wsl --set-default-version 2`\n   - `wsl --set-version Ubuntu-24.04 2`\n\n## Optionally Install Podman/Docker/Docker-Compose/Kubectl/Minikube/Helm Client CLIs (feel free to skip)\n\n1. **Re-Enter Ubuntu under WSL**:\u003cbr/\u003e\n   Re-Enter Ubuntu GNU/Linux under Windows Subsystem for Linux again.\n\n   \u003e Rationale: we have to operate inside Ubuntu here again.\n\n   - *START* \u0026rarr; `wsl terminal` \u003ckbd\u003eRETURN\u003c/kbd\u003e\n\n2. **Install Podman/Skopeo/Buildah**:\u003cbr/\u003e\n   Install Podman, the daemon-less Docker alternative, and its companion tools\n   Skopeo (registry access) and Buildah (container build).\n\n   \u003e Rationale: Podman is a Docker-compatible daemon-less way to run containers.\n   \u003e Notice that In WSL there are no systemd(8) and journald(8) daemons running,\n   \u003e so the environment has to be slightly adjusted to allow podman to work correctly.\n\n   - `(. /etc/os-release;\n     echo \"deb https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/testing/xUbuntu_${VERSION_ID}/ /\" | sudo tee /etc/apt/sources.list.d/devel:kubic:libcontainers:testing.list;\n     curl -skL \"https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/testing/xUbuntu_${VERSION_ID}/Release.key\" | sudo apt-key add - ) \u0026\u0026\n     sudo apt update -y;\n     sudo apt install -y podman skopeo buildah`\n\n   - `sed -e 's;^# cgroup_manager = .*;cgroup_manager = \"cgroupfs\";'\n      -e 's;^# events_logger = .*;events_logger = \"file\";'\n      \u003c/usr/share/containers/containers.conf \u003e/tmp/containers.conf;\n      sudo install -c -m 644 /tmp/containers.conf /etc/containers/containers.conf; rm /tmp/containers.conf`\n\n3. **Install Docker/Docker-Compose**:\u003cbr/\u003e\n   Install original native Linux version of the Docker and Docker-Compose CLIs.\n\n   \u003e Rationale: the original native Linux versions works more flawless than executing the Windows versions under WSL.\n\n   - `curl -skL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - \u0026\u0026`\n     `sudo add-apt-repository \"deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable\" \u0026\u0026`\n     `sudo apt update -y \u0026\u0026`\n     `sudo apt install -y docker-ce docker-ce-cli`\n\n   - `V=$(curl -skL https://github.com/docker/compose/releases | egrep 'releases/tag/v[0-9.]*\"' | sed -e 's;^.*releases/tag/v;;' -e 's;\".*$;;' | head -1);`\n     `sudo curl -skL https://github.com/docker/compose/releases/download/v${V}/docker-compose-linux-x86_64 -o /usr/libexec/docker/cli-plugins/docker-compose; sudo chmod 755 /usr/libexec/docker/cli-plugins/docker-compose`\n\n4. **Install Kubectl/Minikube/Helm**:\u003cbr/\u003e\n   Install the Kubernetes client kubectl(1), the Kubernetes all-in-one server minikube(8) and the Kubernetes package manager helm(1).\n\n   \u003e Rationale: when dealing with the Kubernetes world of containers, those two CLIs are essential.\n\n   - `sudo curl -skL https://storage.googleapis.com/kubernetes-release/release/$(curl -skL https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl -o /usr/local/bin/kubectl \u0026\u0026`\n     `sudo chmod 755 /usr/local/bin/kubectl`\n\n   - `sudo curl -skL https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 -o /usr/local/bin/minikube;`\n     `sudo chmod 755 /usr/local/bin/minikube`\n\n   - `V=$(curl -skL https://github.com/kubernetes/helm/releases | egrep 'releases/tag/v3\\.[0-9.]*\"' | sed -e 's;^.*releases/tag/v;;' -e 's;\".*$;;' | head -1);`\n     `curl -skL $(printf \"%s%s\" https://get.helm.sh/helm-v${V}-linux-amd64.tar.gz) | sudo tar -z -x -f - --strip-components=1 -C /usr/local/bin linux-amd64/helm; sudo chmod 755 /usr/local/bin/helm`\n\n## Optionally Establish DockerD/ContainerD as Container Runtime (Alternative 1, WSL2 only) (feel free to skip)\n\nPro: the original and no root permissions required for docker(1) and docker-compose(1) calls\u003cbr/\u003e\nCon: intransparent and slowed down development\n\n1. **Allow Access to Daemon**\u003cbr/\u003e\n   Allow the current user access to the Docker daemon.\n\n   - `sudo usermod -aG docker $USER`\n\n2. **Configure User Environment**:\u003cbr/\u003e\n   Configure the user environment to auto-start the Docker daemon.\n\n   \u003e Rationale: WSL has no init scripts, so start the Docker daemon manually when the shell is opened.\n\n   - `vi ~/.dotfiles/bashrc`\u003cbr/\u003e\n     \u0026rarr; `(sudo service docker start || true) \u003e/dev/null 2\u003e\u00261`\n\n## Optionally Establish Podman as Container Runtime (Alternative 2, WSL2 only) (feel free to skip)\n\nPro: fully transparent and fast Open Source development\u003cbr/\u003e\nCon: the clone and root permissions required for docker(1) and docker-compose(1) calls\n\n1. **Provide Docker REST API Service**:\u003cbr/\u003e\n   Let Podman provide the Docker REST API as a Unix domain socket under the usual `/var/run/docker.sock` path.\n\n   \u003e Rationale: Docker-Compose requires this access method.\n\n   - `curl -L \"https://fdit-gitlab.dit.htwk-leipzig.de/martin.meszaros/wsl2-podman-compose/-/raw/master/podman-service?inline=false\" \u003epodman-service;`\n     `install -c -m 755 podman-service /etc/init.d/; rm podman-service`\n\n2. **Configure User Environment**:\u003cbr/\u003e\n   Configure the user environment to auto-start the Docker REST API of Podman.\n\n   \u003e Rationale: WSL has no init scripts, so start the Podman socket service manually when the shell is opened.\n\n   - `vi ~/.dotfiles/bashrc`\u003cbr/\u003e\n     \u0026rarr; `(sudo service podman-service start || true) \u003e/dev/null 2\u003e\u00261`\n\n3. **Substitute Docker CLI**\u003cbr/\u003e\n   Substitute the call-compatible podman(1) for docker(1).\n\n   - `sudo apt remove docker-ce docker-ce-cli`\n   - `sudo sh -c '(echo \"#!/bin/sh\"; echo \"exec /usr/bin/podman \\\"\\$@\\\"\") \u003e/usr/local/bin/docker \u0026\u0026 chmod 755 /usr/local/bin/docker'`\n\n## Optionally Establish Docker for Windows as Container Runtime (Alternative 3, Host only) (feel free to skip)\n\nPro: Docker available also on the host, Kubernetes included\u003cbr/\u003e\nCon: intransparent and slowed down development, no longer free for large Enterprise use\n\n1. **Install Docker Desktop**:\u003cbr/\u003e\n   Install the Docker Desktop for Windows (Community Edition) distribution.\n\n   \u003e Rationale: you want Docker container engine be available on the host.\n\n   - *START* \u0026rarr; `control panel` \u0026rarr; *Programs* \u0026rarr; *Programs and Features*\n     \u0026rarr; *Turn Windows features on or off* \u0026rarr; *Hyper-V*\n     (a reboot is required)\n\n   - [Docker Desktop](https://www.docker.com/products/docker-desktop) \u0026rarr; *Download for Windows*\n     (a reboot is required)\n\n   - *START* \u0026rarr; `computer management` \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Run as administrator*\n   - *Computer Management* \u0026rarr; *System Tools* \u0026rarr; *Local Users and Groups* \u0026rarr; *Groups* \u0026rarr; `docker-users` \u0026rarr; \u003ckbd\u003eLEFT-DOUBLE-CLICK\u003c/kbd\u003e \u0026rarr; *Add...*\n     (ensure that your user is really in this group -- usually it is the case by default)\n\n   \u003e Notice: You need a Docker Hub account for downloading and using Docker Desktop.\n   \u003e [Sign up](https://hub.docker.com/signup) first if you still don't have a Docker Hub account.\n\n   \u003e Notice: Yes, Hyper-V is necessary as Docker Desktop for Windows (in\n   \u003e contrast to the regular Docker for Linux) runs Docker inside a\n   \u003e small Linux distribution which is executed in a virtual machine via\n   \u003e Hyper-V. \n\n2. **Start \u0026 Configure Docker Desktop**:\u003cbr/\u003e\n   Start and configure Docker Desktop.\n\n   \u003e Rationale: for CLI access from within WSL 1, the Docker daemon API has to be exposed via TCP on localhost.\n   \u003e For WSL 2 Docker for Windows has a special type of integration which does not need this any longer.\n\n   - *START* \u0026rarr; `docker desktop` \u003ckbd\u003eRETURN\u003c/kbd\u003e\n   - *System Tray* \u0026rarr; *Docker Desktop* \u0026rarr; \u003ckbd\u003eRIGHT-CLICK\u003c/kbd\u003e \u0026rarr; *Settings* \u0026rarr; *General* \u0026rarr; *Expose daemon...*\n\n3. **Re-Enter Ubuntu under WSL**:\u003cbr/\u003e\n   Re-Enter Ubuntu GNU/Linux under Windows Subsystem for Linux again.\n\n   \u003e Rationale: we have to install also the Unix client side of Docker.\n\n   - *START* \u0026rarr; `wsl terminal` \u003ckbd\u003eRETURN\u003c/kbd\u003e\n\n4. **Configure User Environment**:\u003cbr/\u003e\n   Configure the user environment to access Docker for Windows on the host.\n\n   \u003e Rationale: the access works through the TCP socket instead of the usual Unix domain socket.\n\n   - `vi ~/.dotfiles/bashrc`\u003cbr/\u003e\n     \u0026rarr; `export DOCKER_HOST=tcp://localhost:2375`\n\n## Optionally install Language Runtimes (feel free to skip)\n\n1. **Install Node.js**:\u003cbr/\u003e\n   Install the Node.js JavaScript language runtime.\n\n   \u003e Rationale: you want a reasonable JavaScript environment available.\n\n   - `curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -`\n   - `sudo apt install -y nodejs`\n\n2. **Install OpenJDK**:\u003cbr/\u003e\n   Install the OpenJDK Java language runtime.\n\n   \u003e Rationale: you want a reasonable Java environment available.\n\n   - `sudo apt install -y default-jdk`\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Funix-under-windows","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frse%2Funix-under-windows","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Funix-under-windows/lists"}