https://github.com/rse/unix-under-windows

Unix Environment under Windows
https://github.com/rse/unix-under-windows

docker dotfiles environment mintty ubuntu unix windows wsl

Last synced: 3 months ago
JSON representation

Unix Environment under Windows

• Host: GitHub
• URL: https://github.com/rse/unix-under-windows
• Owner: rse
• Created: 2019-04-27T21:32:13.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2024-07-20T21:57:53.000Z (4 months ago)
• Last Synced: 2024-07-20T22:52:47.448Z (4 months ago)
• Topics: docker, dotfiles, environment, mintty, ubuntu, unix, windows, wsl
• Size: 813 KB
• Stars: 32
• Watchers: 7
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

• jimsghstars - rse/unix-under-windows - Unix Environment under Windows (Others)

README

        




Author: [Dr. Ralf S. Engelschall](mailto:[email protected])


Version: 2.4.5 (2024-07-20)

# Unix Environment under Windows

This is a documentation on how to setup a reasonable but opinionated Unix development environment under

[*Microsoft Windows 10/11*](https://windows.com) (Pro edition, 64-bit mode, version ≥ 1809) with the help of the

native [*Windows Subsystem for Linux (WSL)*](https://devblogs.microsoft.com/commandline/),

the [*Ubuntu*](https://www.ubuntu.com/) GNU/Linux distribution,

Dr. Ralf S. Engelschall's [*Unix dotfiles*](https://github.com/rse/dotfiles) shell environment,

the terminal emulator [*MinTTY/WSLTTY*](https://github.com/mintty/wsltty) and

the [*Docker Desktop for Windows*](https://www.docker.com/products/docker-desktop)

container execution platform.

![screenshot](screenshot.png)

> Notice: In short, the crux of this setup in contrast to the usual standard WSL setups is:

>

> - convenient root access (password-less `sudo`)

> - reasonably mapped home directory (`/c/Users/$USER`)

> - essential Unix shell configurations for Bash, Vim, Vifm, TMux and Git ("dot-files")

> - essential Unix shell tools (OpenSSH, RSYNC, etc)

> - additional WSL shell tools (`wsl-open`)

> - improved host terminal emulator (MinTTY/WSLTTY)

> - host SSH agent with transparent access from within WSL (`weasel-pageant`)

> - Docker and Kubernetes client CLIs

> - optionally, Docker runtimes inside WSL (DockerD, Podman) or on host (Docker for Windows)

> - optionally, essential programming language runtime (JavaScript/Java)

## Install Windows Subsystem for Linux (WSL)

1. **Ensure Windows 10/11 Professional/Enterprise, 64 Bit, Version ≥ 18.09**:


   Ensure you are running at least Windows 10 Professional or Windows 10

   Enterprise in 64-bit mode and in Version 1809 (October 2018), 1903

   (April 2019), 1909 (November 2019) or newer (including Windows 11).

   > Rationale: Windows Subsystem for Linux (WSL) is available only

   > under those Windows editions, only under 64-bit and in a reasonable

   > fashion only under at least this version or newer.

   > Windows 10 in Version 1809 is the bare minimum. The recommended

   > system is at least Windows 10 in Version 1909 or newer (including Windows 11).

   - *START* → *Settings* → *System* → *About*:

   - ... *Device Specifications* → *System type*

   - ... *Windows Specifications* → *Edition*

   - ... *Windows Specifications* → *Version*

   Notice:

   > If you have a different edition or you are running in 32-bit mode,

   > you are out of luck with WSL. Sorry, then you have to went with

   > [MSYS2](https://www.msys2.org/) or [Cygwin](https://www.cygwin.com/).

   > If you want to perform a fresh Windows 10/11 installation, start over with Microsoft's

   > [Download Windows 10 Disc Image (ISO File)](https://www.microsoft.com/en-us/software-download/windows10ISO/)

   > or [Download Windows 11 Disc Image (ISO File)](https://www.microsoft.com/software-download/windows11).

   > If you just still have an older Windows version, upgrade with one of the following

   > options:

   >

   > - Windows Updates: *START* → `windows update settings` RETURN

   > - Windows Upgrades: [Windows 10 Update Assistant](https://www.microsoft.com/software-download/windows10)

   > - Windows Upgrades: [Windows 11 Update Assistant](https://www.microsoft.com/software-download/windows10)

2. **Enable Windows Subsystem for Linux**:


   Enable the Windows feature *Windows Subsystem for Linux*.

   A reboot might be necessary.

   > Rationale: Windows Subsystem for Linux is the core feature we want to use.

   - *START* → `powershell` → RIGHT-CLICK → *Run as administrator*

   - `Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux`

   Alternatively:

   - *START* → `cmd` → RIGHT-CLICK → *Run as administrator*

   - `dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart`

   Alternatively:

   - *START* → `control panel` → *Programs* → *Programs and Features*

     → *Turn Windows features on or off* → *Windows-Subsystem for Linux*

   > Notice: In case you have trouble to enable *Windows Subsystem for Linux*, this can have many reasons.

   > In most cases, the reason is that point (1) above is not exactly fulfilled. Start over there again.

3. **Enable "Virtual Machine Platform" Feature**


   Enable the Windows feature *Virtual Machine Platform* (required for WSL2).

   A reboot might be necessary.

   > Rationale: WSL2 is recommended.

   - *START* → `powershell` → RIGHT-CLICK → *Run as administrator*

   - `Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform`

   Alternatively:

   - *START* → `cmd` → RIGHT-CLICK → *Run as administrator*

   - `dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart`

   Alternatively:

   - *START* → `control panel` → *Programs* → *Programs and Features*

     → *Turn Windows features on or off* → *Virtual Machine Platform*

4. **Install/Update WSL2 Linux Kernel**


   Update the WSL2 Linux kernel.

   > Rationale: WSL2 Linux kernel has to be up-to-date or WSL2 will complain.

   - Visit the Microsoft [WSL2 Information Page](https://aka.ms/wsl2kernel)

     and [download and run the MSI installer](https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi)

     for the WSL 2 Linux Kernel.

5. **Enable Hardware Virtualization**


   Enable the CPU Hardware Virtualization in the PC BIOS (required for WSL2).

   - Reboot your system

   - Hold "DELETE" key during boot.

   - Enable CPU Hardware Virtualization (VT-x/VMX).

6. **Update WSL**:


   Update to the latest version of *Windows Subsystem for Linux*.

   - *START* → `powershell` → RIGHT-CLICK → *Run as administrator*

   - `wsl.exe --update`

## Install Ubuntu GNU/Linux Operating System

1. **Install Ubuntu 24.04 LTS**:


   Install Ubuntu GNU/Linux 24.04 Long Term Support (LTS) from the Microsoft Store.

   > Rationale: you need a reasonable GNU/Linux distribution and it should receive updates for a longer time.

   - *START* → `microsoft store` → *Search* → `ubuntu 24.04 lts` → *Install*

   > Notice: In case the Microsoft Store is not available on your system, the reason

   > can be that you still have User Account Control (UAC) disabled, or

   > you are still not signed in with a Microsoft Account (although it

   > should be not required), or your Windows is still not activated or

   > you are still running an evaluation version of Windows. Anyway, try

   > to fix the problems the following way:

   > 

   > - *START* → *Settings* → *Updates & Security* → *Troubleshoot* → *Windows Store Apps* → *Run the troubleshooter*

## Setup Ubuntu GNU/Linux Operating System

1. **Enter Ubuntu under WSL**:


   Enter Ubuntu GNU/Linux under Windows Subsystem for Linux.

   > Rationale: we have to setup Ubuntu from itself.

    - *START* → *Ubuntu 24.04*

   Just be patient on first launch, it really takes time.

   Then, when asked for your username, enter the same as your Windows username.

   When asked for your password, enter either your Windows password or another one, but

   remember it (at least once until the step where we configure sudo(8) below)!

   For all other questions, keep the defaults.

2. **Enable Convenient Root Access**:


   Ensure no password is needed for subsequent root access.

   > Rationale: just convenience only -- feel free to ignore if you want to enter your password over and over again.

    - `sudo vi /etc/sudoers`


      ← `%sudo ALL=(ALL:ALL) ALL`


      → `%sudo ALL=(ALL:ALL) NOPASSWD: ALL`

3. **Upgrade Ubuntu Operating System**:


   Upgrade to the latest package versions of Ubuntu and allow APT to use HTTPS.

   > Rationale: you always want the latest updates and Docker later needs HTTPS access.

   - `sudo apt update -y &&`


     `sudo apt upgrade -y --with-new-pkgs &&`


     `sudo apt install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common`

4. **Mount Windows directories in WSL with Meta-Data enabled**:


   Configure the mounting of Windows directories in WSL (`/c` instead of `/mnt/c`) and with *Meta-Data* enabled.

   > Rationale: allow POSIX file permissions on Windows drives from within WSL.

    - `sudo vi /etc/wsl.conf`


      → `[boot]`


      → `systemd = true`


      → `[automount]`


      → `enabled = true`


      → `root    = /`


      → `options = "metadata,umask=022"`

5. **Use Combined Home Directory**:


   Map the Unix home directory to the regular Windows home directory.

   > Rationale: just convenience only -- feel free to ignore.

   - *START* → `cmd`

   - `wsl --shutdown`

   - `wsl -u root usermod -d /c/Users/%USERNAME% %USERNAME%`

6. **Activate Filesystem Layout**:


   Perform a logout/login cycle on the host system to

   activate the new filesystem layout (mapping of /c and home directory)

   > Rationale: WSL does not re-mount the filesystem without a logout/login or reboot

## Configure Unix Shell Environment

1. **Re-Enter Ubuntu under WSL**:


   Re-Enter Ubuntu GNU/Linux under Windows Subsystem for Linux again.

   > Rationale: we have to configure the Unix environment from itself.

    - *START* → *Ubuntu 24.04*

2. **Install Essential Unix Tools**:


   Install all necessary essential and some more useful Unix tools.

   > Rationale: the subsequent Unix Shell Configurations are partially based on them and you really want a decent Unix environment.

   First, install the tools which available via standard package manager:

   - `sudo apt install -y bash less vim vifm tmux && `


     `sudo apt install -y procps lsof dnsutils tcpdump && `


     `sudo apt install -y openssh-client stunnel subversion git curl && `


     `sudo apt install -y mc tree file findutils && `


     `sudo apt install -y rsync rdup rclone restic w3m lftp && `


     `sudo apt install -y atool gzip bzip2 xz-utils zip unzip && `


     `sudo apt install -y diffutils diffstat patch patchutils par && `


     `sudo apt install -y openssl gnupg golang-cfssl apg uuid bc && `


     `sudo apt install -y imagemagick ghostscript poppler-utils && `


     `sudo apt install -y gcc g++ bison flex`

   Second, install the tool [FZF](https://github.com/junegunn/fzf) which is not available

   (at least not in latest version) via standard package manager:

   - `curl -skLO https://github.com/junegunn/fzf/releases/download/v0.54.1/fzf-0.54.1-linux_amd64.tar.gz && `


     `tar zxf fzf-*-linux_amd64.tar.gz && `


     `sudo install -c -m 755 fzf /usr/local/bin/ && `


     `rm fzf fzf-*-linux_amd64.tar.gz`

3. **Optionally Install Additional Unix Tools**:


   Install additionally useful Unix tools.

   > Rationale: Git-Town and TTY2Web are often useful.

   - `curl -skLO https://github.com/git-town/git-town/releases/download/v14.3.1/git-town_linux_intel_64.deb && `


     `sudo dpkg -i git-town_*.deb && `


     `rm git-town_*.deb && `


     `curl -skLO https://github.com/kost/tty2web/releases/download/v3.0.3/tty2web_linux_amd64 && `


     `sudo install -c -m 755 tty2web* /usr/local/bin/tty2web && `


     `rm tty2web*`

4. **Install Unix Shell Configurations**:


   Install Dr. Ralf S. Engelschall's essential Unix dotfiles.

   > Rationale: you really want a reasonable pre-configured Unix shell environment.

   - `sudo apt install -y make && `


     `curl -skLO https://github.com/rse/dotfiles/archive/master.zip && `


     `unzip -x master.zip && `


     `(cd dotfiles-master && sudo make install) && `


     `rm -rf dotfiles-master && `


     `rm master.zip && `


     `dotfiles -f ~`

5. **Install UTF-8 locale information**:


   Install the UTF-8 locale information into the system.

   > Rationale: prevent Bash from complaining afterwards.

   - `sudo localedef -i en_US -f UTF-8 en_US.UTF-8`

6. **Install Unix Shell Addon Configurations**:


   Install Dr. Ralf S. Engelschall's Bash-FZF and Bash-ENVRC addons.

   > Rationale: you really want a reasonable pre-configured Unix shell environment.

   > This especially includes an improved CTRL+r functionality in Bash, which then opens

   > an FZF-based search functionality (which you can see in the screenshot above, too).

   - `curl -skL https://raw.githubusercontent.com/rse/bash-fzf/master/bash-fzf.rc -o ~/.bash-fzf.rc && `


     `curl -skL https://raw.githubusercontent.com/rse/bash-envrc/master/bash-envrc.rc -o ~/.bash-envrc.rc && `


     `exec bash`


   - `cdpaths -g`

7. **Optionally Extend Unix Shell Configurations**:


   Extend the Unix shell configuration with your personal information.

   > Rationale: these informations individualize your environment (replace the `` placeholders, please).

   - `vi ~/.dotfiles/gitconfig`


     → `[user]`


     → `user  = `


     → `name  =  `


     → `email = .@`


8. **Install WSL Utilities**:


   Install additional WSL utilities.

   > Rationale: you want additional features inside WSL.

   - `sudo apt install -y ubuntu-wsl wslu && `


     `curl -skLO https://github.com/4U6U57/wsl-open/archive/master.zip && `


     `unzip -x master.zip && `


     `sudo install -c -m 755 wsl-open-master/wsl-open.sh /usr/local/bin/wsl-open && `


     `sudo mkdir -p /usr/local/share/man/man1 && `


     `sudo install -c -m 644 wsl-open-master/wsl-open.1 /usr/local/share/man/man1/ && `


     `rm -rf wsl-open-master && `


     `rm master.zip`

   - `curl -skLO https://github.com/CzBiX/WSLHostPatcher/releases/download/v0.1.3/WSLHostPatcher.zip && `


     `unzip -x WSLHostPatcher.zip && `


     `mkdir -p ~/AppData/Local/WSLHostPatcher && `


     `chmod 755 WSLHostPatcher.exe && `


     `mv WSLHostPatch.dll WSLHostPatcher.exe ~/AppData/Local/WSLHostPatcher/ && `


     `rm -f WSLHostPatcher.zip WSLHostPatch*.*`

   - `vi ~/.dotfiles/bashrc`


      → `PATH=$PATH:/c/Windows/System32/WindowsPowerShell/v1.0/`


      → `alias wsl="/c/Windows/System32/wsl.exe"`


      → `alias cmd="/c/Windows/System32/cmd.exe"`


      → `alias wsl-host-patcher="$HOME/AppData/Local/WSLHostPatcher/WSLHostPatcher.exe"`


      → `alias open=wsl-open`

9. **Optionally avoid system messages**:


   Force the system to not display messages.

   > Rationale: you don't want to be nerved with those messages

   - `touch ~/.hushlogin`

## Install MinTTY/WSLTTY Terminal Emulator

1. **Install MinTTY/WSLTTY**:


   Install the WSLTTY variant of MinTTY.

   > Rationale: a reasonable terminal emulator has to be used and the default WSL console is not good enough.

   - [WSLTTY version ≥ 3.7.1](https://github.com/mintty/wsltty/releases) → `wsltty-*-install.exe`

   - WIN+r → `%LOCALAPPDATA%\wsltty` → `add to context menu.lnk`

2. **Install DejaVu Sans Mono font**:


   Install a perfect monospaced font for the terminal emulator.

   > Rationale: MinTTY/WSLTTY configuration below references it.

   - download: [DejaVu Sans ≥ 2.37](https://dejavu-fonts.github.io/Download.html) → `dejavu-fonts-ttf-*.zip`

   - extract: `dejavu-fonts-ttf-*.zip` → RIGHT-CLICK *Extract all*

   - install: `dejavu-fonts-ttf-*\ttf\` → select all `*.ttf` → RIGHT-CLICK → *Install*

3. **Install MinTTY/WSLTTY Configuration**:


   Install Dr. Ralf S. Engelschall's MinTTY/WSLTTY configuration.

   > Rationale: reasonable colors and fonts should be used in the terminal emulator.

   - download: [MinTTY-config](https://github.com/rse/mintty-config/archive/master.zip)

   - extract: `master.zip` → RIGHT-CLICK *Extract all*

   - copy: `mintty-config-master\config`

   - paste: `%APPDATA%\wsltty` (override `config` file)

4. **Optionally Make MinTTY/WSLTTY easily accessible**:


   Pin MinTTY/WSLTTY to the Windows taskbar and additionally assign it to the global Windows hotkey CTRL+ALT+c.

   > Rationale: easy and quick access to the Unix shell

   - *START* → `wsl terminal` → RIGHT-CLICK *Pin to taskbar*.

   - Taskbar → *WSL Terminal* → RIGHT-CLICK → *WSL Terminal* →


   - ...RIGHT-CLICK → *Properties* → *Shortcut key* → CTRL+ALT+c.



## Optionally Install Secure-Shell (SSH) Environment (feel free to skip)

1. **Install PuTTY**:


   Install the PuTTY SSH client.

   > Rationale: you want to run the PuTTY Agent (`pageant`) for reasonable SSH agent support.

   - [PuTTY Downloads](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) → `putty-64bit-*-installer.msi`

2. **Generate SSH Key**:


   Generate (or use existing) SSH key.

   > Rationale: you don't want to use passwords, of course.

   - *START* → `puttygen` RETURN

   - → *Generate*

   - → *Key passphrase* & *Confirm passphrase*

   - → *Save public key* → `c:\Users\\Documents\ssh-key-pub.pem`

   - → *Save private key* → `c:\Users\\Documents\ssh-key-prv.ppk`

   - → *Conversions* → *Export OpenSSH key* → `c:\Users\\Documents\ssh-key-prv.pem`.


3. **Autostart PuTTY Agent**:


   Enable the PuTTY Agent to autostart on login and load the SSH private key.

   > Rationale: you want it to be running all the time.

   - WIN+e → `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup` → RIGHT-CLICK → *New* → *Shortcut*

   - `"C:\Program Files\PuTTY\pageant.exe" "C:\Users\\Documents\ssh-key-prv.ppk"`

5. **Install PuTTY Agent Client (Weasel-Pageant)**


   Install Weasel-Pageant for accessing the PuTTY Agent from within WSL.

   > Rationale: you want to directly access PuTTY Agent from within WSL.

   - [Weasel-Pageant Downloads](https://github.com/vuori/weasel-pageant/releases) → `weasel-pageant-1.4.zip`

   - `weasel-pageant-1.4.zip` → RIGHT-CLICK → *Extract all*

   - move `weasel-pageant-1.4\` to `%APPDATA%\weasel-pageant\`

4. **Enter Ubuntu under WSL via MinTTY/WSLTTY**:


   Re-Enter Ubuntu GNU/Linux under Windows Subsystem for Linux again (this time via MinTTY/WSLTTY).

   > Rationale: we have to configure also the Unix version of SSH.

    - *START* → `wsl terminal` RETURN

5. **Configure Unix Environment for SSH Agent**:


   Configure the Unix environment to use the Weasel-Pageant as the SSH agent.

   > Rationale: in every WSL terminal you want SSH agent access available automatically.

   - `vi ~/.dotfiles/bashrc`


     → `eval $(~/AppData/Roaming/weasel-pageant/weasel-pageant -r -s)`

## Optionally Enable Windows Subsystem for Linux (WSL) Version 2 (Windows 10/11 Version >= 19.03 only) (feel free to skip)

2. **Switch to use WSL 2**

   - *START* → `cmd`

   - `wsl --set-default-version 2`

   - `wsl --set-version Ubuntu-24.04 2`

## Optionally Install Podman/Docker/Docker-Compose/Kubectl/Minikube/Helm Client CLIs (feel free to skip)

1. **Re-Enter Ubuntu under WSL**:


   Re-Enter Ubuntu GNU/Linux under Windows Subsystem for Linux again.

   > Rationale: we have to operate inside Ubuntu here again.

   - *START* → `wsl terminal` RETURN

2. **Install Podman/Skopeo/Buildah**:


   Install Podman, the daemon-less Docker alternative, and its companion tools

   Skopeo (registry access) and Buildah (container build).

   > Rationale: Podman is a Docker-compatible daemon-less way to run containers.

   > Notice that In WSL there are no systemd(8) and journald(8) daemons running,

   > so the environment has to be slightly adjusted to allow podman to work correctly.

   - `(. /etc/os-release;

     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;

     curl -skL "https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/testing/xUbuntu_${VERSION_ID}/Release.key" | sudo apt-key add - ) &&

     sudo apt update -y;

     sudo apt install -y podman skopeo buildah`

   - `sed -e 's;^# cgroup_manager = .*;cgroup_manager = "cgroupfs";'

      -e 's;^# events_logger = .*;events_logger = "file";'

      /tmp/container.conf;

      sudo install -c -m 644 /tmp/containers.conf /etc/containers/containers.conf; rm /tmp/containers.conf`

3. **Install Docker/Docker-Compose**:


   Install original native Linux version of the Docker and Docker-Compose CLIs.

   > Rationale: the original native Linux versions works more flawless than executing the Windows versions under WSL.

   - `curl -skL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - &&`

     `sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" &&`

     `sudo apt update -y &&`

     `sudo apt install -y docker-ce docker-ce-cli`

   - `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);`

     `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`

4. **Install Kubectl/Minikube/Helm**:


   Install the Kubernetes client kubectl(1), the Kubernetes all-in-one server minikube(8) and the Kubernetes package manager helm(1).

   > Rationale: when dealing with the Kubernetes world of containers, those two CLIs are essential.

   - `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 &&`

     `sudo chmod 755 /usr/local/bin/kubectl`

   - `sudo curl -skL https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 -o /usr/local/bin/minikube;`

     `sudo chmod 755 /usr/local/bin/minikube`

   - `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);`

     `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`

## Optionally Establish DockerD/ContainerD as Container Runtime (Alternative 1, WSL2 only) (feel free to skip)

Pro: the original and no root permissions required for docker(1) and docker-compose(1) calls


Con: intransparent and slowed down development

1. **Allow Access to Daemon**


   Allow the current user access to the Docker daemon.

   - `sudo usermod -aG docker $USER`

2. **Configure User Environment**:


   Configure the user environment to auto-start the Docker daemon.

   > Rationale: WSL has no init scripts, so start the Docker daemon manually when the shell is opened.

   - `vi ~/.dotfiles/bashrc`


     → `(sudo service docker start || true) >/dev/null 2>&1`

## Optionally Establish Podman as Container Runtime (Alternative 2, WSL2 only) (feel free to skip)

Pro: fully transparent and fast Open Source development


Con: the clone and root permissions required for docker(1) and docker-compose(1) calls

1. **Provide Docker REST API Service**:


   Let Podman provide the Docker REST API as a Unix domain socket under the usual `/var/run/docker.sock` path.

   > Rationale: Docker-Compose requires this access method.

   - `curl -L "https://fdit-gitlab.dit.htwk-leipzig.de/martin.meszaros/wsl2-podman-compose/-/raw/master/podman-service?inline=false" >podman-service;`

     `install -c -m 755 podman-service /etc/init.d/; rm podman-service`

2. **Configure User Environment**:


   Configure the user environment to auto-start the Docker REST API of Podman.

   > Rationale: WSL has no init scripts, so start the Podman socket service manually when the shell is opened.

   - `vi ~/.dotfiles/bashrc`


     → `(sudo service podman-service start || true) >/dev/null 2>&1`

3. **Substitute Docker CLI**


   Substitute the call-compatible podman(1) for docker(1).

   - `sudo apt remove docker-ce docker-ce-cli`

   - `sudo sh -c '(echo "#!/bin/sh"; echo "exec /usr/bin/podman \"\$@\"") >/usr/local/bin/docker && chmod 755 /usr/local/bin/docker'`

## Optionally Establish Docker for Windows as Container Runtime (Alternative 3, Host only) (feel free to skip)

Pro: Docker available also on the host, Kubernetes included


Con: intransparent and slowed down development, no longer free for large Enterprise use

1. **Install Docker Desktop**:


   Install the Docker Desktop for Windows (Community Edition) distribution.

   > Rationale: you want Docker container engine be available on the host.

   - *START* → `control panel` → *Programs* → *Programs and Features*

     → *Turn Windows features on or off* → *Hyper-V*

     (a reboot is required)

   - [Docker Desktop](https://www.docker.com/products/docker-desktop) → *Download for Windows*

     (a reboot is required)

   - *START* → `computer management` RIGHT-CLICK → *Run as administrator*

   - *Computer Management* → *System Tools* → *Local Users and Groups* → *Groups* → `docker-users` → LEFT-DOUBLE-CLICK → *Add...*

     (ensure that your user is really in this group -- usually it is the case by default)

   > Notice: You need a Docker Hub account for downloading and using Docker Desktop.

   > [Sign up](https://hub.docker.com/signup) first if you still don't have a Docker Hub account.

   > Notice: Yes, Hyper-V is necessary as Docker Desktop for Windows (in

   > contrast to the regular Docker for Linux) runs Docker inside a

   > small Linux distribution which is executed in a virtual machine via

   > Hyper-V. 

2. **Start & Configure Docker Desktop**:


   Start and configure Docker Desktop.

   > Rationale: for CLI access from within WSL 1, the Docker daemon API has to be exposed via TCP on localhost.

   > For WSL 2 Docker for Windows has a special type of integration which does not need this any longer.

   - *START* → `docker desktop` RETURN

   - *System Tray* → *Docker Desktop* → RIGHT-CLICK → *Settings* → *General* → *Expose daemon...*

3. **Re-Enter Ubuntu under WSL**:


   Re-Enter Ubuntu GNU/Linux under Windows Subsystem for Linux again.

   > Rationale: we have to install also the Unix client side of Docker.

   - *START* → `wsl terminal` RETURN

4. **Configure User Environment**:


   Configure the user environment to access Docker for Windows on the host.

   > Rationale: the access works through the TCP socket instead of the usual Unix domain socket.

   - `vi ~/.dotfiles/bashrc`


     → `export DOCKER_HOST=tcp://localhost:2375`

## Optionally install Language Runtimes (feel free to skip)

1. **Install Node.js**:


   Install the Node.js JavaScript language runtime.

   > Rationale: you want a reasonable JavaScript environment available.

   - `curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -`

   - `sudo apt install -y nodejs`

2. **Install OpenJDK**:


   Install the OpenJDK Java language runtime.

   > Rationale: you want a reasonable Java environment available.

   - `sudo apt install -y default-jdk`