tooling/wsl-setup.org

# -*- ii: ii; -*-
#+TITLE: Windows Subsystem for Linux Setup
#+AUTHOR: James Blair
#+EMAIL: mail@jamesblair.net
#+DATE: 1st September 2019


This guide will walk through setting up [[https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux][Windows Subsystem for Linux]] on Windows 10.  This particular setup contains my opinionated view of a good foundation and layers on some pairing and development orientated tooling over top.

*Caveats:* Please note this guide is written for the [[https://www.microsoft.com/en-us/p/debian/9msvkqc78pk6][Debian WSL distribution]].

*Acknowledgements:* Large elements of this wsl setup came about through collaboration with the great people at [[https://ii.coop][ii.coop]].  I encourage you to explore and contribute to their work on [[https://gitlab.ii.coop][gitlab]] as many elements form a core part of this setup and workflow.


** Step 1 - Setup home folder structure

   After installing the Debian WSL distribution no folders are present in your home folder.
   
   In this section we create some quick standard folders to keep our home folder somewhat organised.

   #+NAME: Setup home folder strucuture
   #+BEGIN_SRC shell
   # Ensure we are in our home folder
   cd ~/
   
   # Create a documents folder for our git repositories
   mkdir Documents

   # Create a downloads folder for temporary objects
   mkdir Downloads
   #+END_SRC


** Step 2 - Update and install packages

   To get started we ensure the package manager is up to date.

   #+NAME: Update system packages
   #+BEGIN_SRC shell
   sudo apt-get update && sudo apt-get upgrade
   #+END_SRC


   Next we install a series of standard packages that form part of our workflow or
   are dependencies for other tools in our environment.

   #+NAME: Install standard packages 
   #+BEGIN_SRC shell
   # Install basic utilities
    sudo apt-get install -y git locales curl wget xclip xsel tmux tmate net-tools less wget htop screenfetch zip openssh-client dictd
  
   # Install pre-requisites for compiling emacs
   sudo apt-get install -y make gcc libgnutls28-dev libtinfo-dev
  
   # Install dpkg and apt management tools
   sudo apt-get install -y software-properties-common apt-transport-https ca-certificates dirmngr

   # Install terminal customisation packages
   sudo apt install -y xterm xtermcontrol
   #+END_SRC


   We use [[https://pandoc.org/][pandoc]] for documentation export from spacemacs and other markup conversion tasks.

   #+NAME: Install pandoc
   #+BEGIN_SRC shell
   # Work from our downloads folder
   cd ~/Downloads

   # Download the latest release from github
   curl -s https://api.github.com/repos/jgm/pandoc/releases/latest \
   | grep "browser_download_url.*deb" \
   | cut -d : -f 2,3 \
   | tr -d \" \
   | wget -i -
   
   # Install the package with dpkg
   sudo dpkg -i pandoc*
   
   # Remove the package file after install
   rm pandoc*
   #+END_SRC


   For additional package management we use [[https://www.npmjs.com/][node package manager]]. The code below installs node ~12~.

   #+NAME: Install node
   #+BEGIN_SRC shell 
   # Curl down the shell script for adding version 12 of nodejs to apt
   sudo curl  -sL https://deb.nodesource.com/setup_12.x | sudo bash -
   
   # Install the nodejs package via apt
   sudo apt-get install -y nodejs
   #+END_SRC

  
   For managing secrets we use [[https://bitwarden.com/][bitwarden]] which provides a great [[https://github.com/bitwarden/cli][cli utility]].

   This section should be expanded in future to cover setting alias for common bitwarden tasks.

   #+NAME: Install bitwarden and login
   #+BEGIN_SRC shell
   # Set an environment variable with our login email for bitwarden
   export account=[BITWARDEN_ACCOUNT]

   # Install the bitwarden cli via node package manager
   sudo npm install -g @bitwarden/cli 

   # Test login to bitwarden
   bw login $account
   #+END_SRC


   For working with google cloud platform we use the [[https://cloud.google.com/sdk/][GCP SDK]], which provides our cli tools.

   #+NAME: Install google cloud sdk
   #+BEGIN_SRC shell
   # Add the Cloud SDK distribution URI as a package source: 
   echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

   # Import the Google Cloud public key: 
   curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

   # Update then install the Google Cloud SDK & kubectl: 
   sudo apt-get update && sudo apt-get install -y google-cloud-sdk kubectl
   #+END_SRC
   
   For working with [[https://aws.com][Amazon Web Services]] we need the [[https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html][AWS CLI]].

   #+NAME: Install amazon web services cli
   #+BEGIN_SRC shell
   cd ~/Downloads/
   curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
   unzip awscliv2.zip
   sudo ./aws/install 
   #+END_SRC 

   For cloud infrastructure deployments we use [[https://www.terraform.io/][terraforms]].

   #+NAME: Install hashicorp terraforms
   #+BEGIN_SRC shell
   # Download the binary
   wget 'https://releases.hashicorp.com/terraform/0.12.18/terraform_0.12.18_linux_amd64.zip'

   # Unzip it
   unzip *.zip

   # Move the binary to path
   sudo mv terraform /usr/local/bin/

   # Clean up
   rm *amd64.zip 
   #+END_SRC


   For ad-hoc system administration we use [[https://deb.nodesource.com/setup_12.x ][ansible]].

   #+NAME: Install ansible
   #+BEGIN_SRC shell
   # Add a source entry to apt sources
   echo 'deb http://ppa.launchpad.net/ansible/ansible/ubuntu trusty main' | sudo tee -a /etc/apt/sources.list
   
   # Add the required key
   sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 93C4A3FD7BB9C367
   
   # Install ansible via apt package manager
   sudo apt-get update && sudo apt-get install -y ansible
   #+END_SRC


** Step 3 - Setup environment dotfiles

   Within wsl we can use .dotfiles to further customise our environment. The script
   below restores my versions of key dotfiles automatically.
   
   *Note:* The git clone below relies on having permission to clone the 
   repository referenced.  For me this means having an ssh key present
   which has been added to gitlab.

   #+NAME: Clone and restore the dotfiles
   #+BEGIN_SRC tmate
   # Clone down this repository
   git clone ssh://git@gitlab.jamma.life:2224/jmhbnz/tooling.git ~/Documents/tooling/
   
   # Restore all dotfiles
   cp ~/Documents/tooling/.* ~/
   
   # Reload bashrc with updated version
   source ~/.bashrc
   #+END_SRC


** Step 4 - Install kubemacs editor

*** Compile and install vanilla emacs

   A key component in our environment is the ii extension of spacemacs. 
   The section below will setup emacs version ~26.3~ and then layer
   the ii version of spacemacs called kubemacs on top.

   Our first step is to download the base emacs 26.3 source code.

   #+NAME: Download and extract emacs source
   #+BEGIN_SRC tmate
   # Work from our downloads directory
   cd ~/Downloads/

   # Download the tarball for emacs 26.3 source code
   wget https://mirror.ossplanet.net/gnu/emacs/emacs-26.3.tar.xz
   
   # Untar the source code archive
   tar xf emacs-26.3.tar.xz

   # Change to the extracted directory
   cd emacs-26.3
   #+END_SRC


   After downloading and untarring the source code we are ready to
   attempt resolving dependencies and compiling.

   We configure without-x as this environment is solely focussed on 
   running within terminal i.e. ~emacs -nw~.

   #+NAME: Compile and install emacs
   #+BEGIN_SRC tmate
   # Run configure to resolve any dependencies minus x window support
   ./configure --without-x --with-gnutls=no
  
   # Compile the application with make, using all available cpu cores
   sudo make -j `nproc`

   # Run make install to move/install compiled binaries
   sudo make install
   #+END_SRC


   After compiling and installing emacs we should verify that version ~26.3~ is
   installed.

   #+NAME: Verify correct emacs version is installed
   #+BEGIN_SRC tmate
   emacs --version  
   #+END_SRC


*** Overlay kubemacs

   Once the right version of emacs is running we can then layer in kubemacs on top
   Documentation for this is here: https://github.com/kubemacs/kubemacs
  
   #+BEGIN_SRC tmate
   # Remove the default site-lisp file
   sudo rm /usr/local/share/emacs/site-lisp/subdirs.el

   # Clone kubemacs from github
   sudo git clone --recursive https://github.com/kubemacs/kubemacs /usr/local/share/emacs/site-lisp/
  
   # Ensure permissions are set for the cloned folder
   sudo chown -R $USER:$USER /usr/local/share/emacs/site-lisp
   #+END_SRC
  

   One final configuration step specific to wsl is to switch from ~osc52~ to ~xsel~ for clipboard. 

   This is required because copy and paste osc52 sequences are not currently supported in wsl.
   You can add your voice to this issue to change that [[https://github.com/microsoft/terminal/issues/2946][here]].

   Additionally there is also a bug within the ~ob-tmate~ kubemacs component that we need to fix.
   This has been fixed upstream and is awaiting merge, refer [[https://github.com/ii/ob-tmate/pull/2][pr #2 here]].

   #+BEGIN_SRC tmate
   # Replace the osc52 command with xsel
   sed -i -e 's/abc/XYZ/g' /usr/local/share/emacs/site-lisp/bin/osc52-tmate.sh

   # Fix the ob-tmate bug
   sed -i -e 's/ob-session dir))/ob-session session-dir))/g' /usr/local/share/emacs/site-lisp/spacemacs/elpa/26.3/develop/ob-tmate-20200206.109/ob-tmate.el 
   #+END_SRC


** Step 5 - Setup mutt email client

   For reading email we ideally use a cli based client for fast searching
   and lightweight mail reading.

   The [[https://gitlab.com/muttmua/mutt/][mutt]] mail client fills these roles well for imap mailboxes.

   The first step to setup mutt is to ensure it is installed.

   #+NAME: Install mutt
   #+BEGIN_SRC shell
   sudo apt-get install mutt urlscan 
   #+END_SRC

   After installing mutt we then need to create configuration directories 
   and files.

   #+NAME: Create mutt config files
   #+BEGIN_SRC shell
   mkdir -p ~/.mutt/cache/headers
   mkdir ~/.mutt/cache/bodies
   touch ~/.mutt/certificates
   touch ~/.muttrc
   #+END_SRC

   One configuration folders and files exist we just need to populate our
   user mutt configuration file with a configuration for our particular 
   mail provider.

   The example below utilises the ~bitwarden~ cli utility for secrets to
   ensure these are securely gathered at runtime and not stored in the file.

   #+NAME: Set mutt configuration
   #+BEGIN_SRC shell
   cat > ~/.muttrc << EOF
   set ssl_starttls=yes
   set ssl_force_tls=yes
   set imap_user=`bw get username hosted`
   set imap_pass=`bw get password hosted`
   set from=`bw get username hosted`
   set realname='James Blair'
   set folder=imaps://mail.jamesblair.net
   set header_cache="~/.mutt/cache/headers"
   set message_cachedir="~/.mutt/cache/bodies"
   set certificate_file="~/.mutt/certificates"
   set smtp_url="smtp://`bw get username hosted`@mail.jamesblair.net:587/"
   set smtp_pass=`bw get password hosted`
   set move=no
   set imap_keepalive=900
   set postponed="=Drafts"
   set record="=Sent"
   set imap_passive=no
   set spoolfile=imaps://mail.jamesblair.net/INBOX
   EOF
   #+END_SRC