Documentation

• 1: Installation Instructions
• 2: How Does It Work
• 3: How to Contribute

wsl --install -d Ubuntu-22.04

# if necessary create user
adduser wsl

# change hostname to avoid confusion with your current distribution
oldName="$(hostname)"
newName="UbuntuTest"
hostname NewName
sed -i -E -e 's/${oldName}/${newName}/' /etc/hosts

mkdir "/mnt/wsl/${WSL_DISTRO_NAME}"
sudo mount --bind / "/mnt/wsl/${WSL_DISTRO_NAME}"

mkdir "/mnt/wsl/${WSL_DISTRO_NAME}"
sudo mount --bind / "/mnt/wsl/${WSL_DISTRO_NAME}"

if [[ ! -d "/mnt/wsl/${WSL_DISTRO_NAME}" ]]; then
  mkdir -p "/mnt/wsl/${WSL_DISTRO_NAME}"
  sudo mount --bind / "/mnt/wsl/${WSL_DISTRO_NAME}"
fi

if [[ ! -d "/mnt/wsl/${WSL_DISTRO_NAME}" ]]; then
  mkdir -p "/mnt/wsl/${WSL_DISTRO_NAME}"
  sudo mount --bind / "/mnt/wsl/${WSL_DISTRO_NAME}"
fi
MASTER_DISTRO=Ubuntu-20.04
if [[ -d "/mnt/wsl/${MASTER_DISTRO}" ]]; then
  mkdir -p ~/projects/bash-dev-env
  sudo mount --bind \
    "/mnt/wsl/${MASTER_DISTRO}/home/wsl/fchastanet/bash-dev-env" \
    ~/projects/bash-dev-env
fi

# from previous distro, sync your important folders
sudo rsync --info=progress2 --no-compress -W -ax projects /mnt/wsl/UbuntuTest/home/wsl
sudo rsync --info=progress2 --no-compress -W -ax fchastanet /mnt/wsl/UbuntuTest/home/wsl
sudo rsync --info=progress2 --no-compress -W -ax /var/lib/docker /mnt/wsl/UbuntuTest/var/lib

# alternatively, you can sync all the necessary directories at once
sudo rsync --info=progress2 --no-compress -W -ax \
  --include=/home/wsl/.history \
  --include=/home/wsl/projects \
  --include=/home/wsl/fchastanet \
  --include=/var/lib/docker \
  --exclude='*' / /mnt/wsl/UbuntuTest

# on target distribution, don't forget to restart docker daemon when the sync is done
sudo service docker restart

1 - Installation Instructions

1. Important Notes to know before executing this script

Important note before beginning

This software has only been tested under Ubuntu distribution.

Additionally to user and root home profile, this script will update some general files of your distribution:

• update /etc/hosts
• add/update /etc/wsl.conf
• add /etc/sudoers.d/${USERNAME}-upgrade-no-password
• add /etc/sudoers.d/bash-dev-env
• update /etc/inputrc
• add file ${HOME}/.bash-dev-env that contains every common environment variable for easier future update
• update /etc/update-manager/release-upgrades following UPGRADE_UBUNTU_VERSION .env variable chosen
• add /etc/cron.d/bash-dev-env-upgrade
• update /etc/passwd using chsh to change default shell following PREFERRED_SHELL .env variable chosen
• add files in /etc/update-motd.d
• update /var/run/motd via update-motd command and /etc/update-motd.d/* files
• add some apt sources list in /etc/apt/sources.list.d/

Only if LXDE configuration used (normally not used on wsl environment):

• /etc/X11/default-display-manager
• add /usr/share/lightdm/lightdm.conf.d/50-ubuntu.conf

On wsl environment, this script generates the following side effects on your windows environment:

• updates %USERPROFILE%\.wslconfig updates memory limits and swap settings conforming to .env file
• install font mesloLGS_NF in %USERPROFILE%\AppData\Local\Microsoft\Windows\Fonts

These files are backed up in <CURRENT_DIR>/backup directory.

2. Profiles

Optionally you can create your own profile in order to add or remove some dependencies.

Profile profile.default.sh is recommended for installing wsl environment.

Profile profile.default.virtualBox.sh actually does a full install of all the dependencies. Note that some dependencies will only be installed on wsl though (eg: WslProfile, DockerDefaultConfig, …).

You can create your own profiles, files have to be named profile.{name}.sh

3. WSL install script

From wsl terminal

eventually copy your ssh private/public key from windows

mkdir -p ~/.ssh && cp "$(wslpath "$(wslvar USERPROFILE)")/.ssh/id_rsa"* ~/.ssh

clone this repository

mkdir -p ~/projects
git clone git@github.com:fchastanet/bash-dev-env.git ~/projects/bash-dev-env

init configuration note that your vscode installed in windows can be launched from WSL using code command.

cd ~/projects/bash-dev-env
cp .env.template .env
code .env

launch the installation for wsl and follow the instructions

./install -p default

That’s it, you’re environment is installed and configured, you are ready to develop !

4. If needed, ability to install software one by one

You also have the ability to install and configure each software independently eg:

./install ShellZsh

5. Additional steps

Using Powershell in admin mode, you can run the following commands to set up port forwarding for WSL:

$HOST_IP = Get-NetIPAddress -InterfaceAlias "vEthernet (WSL*" |`
  Where-Object { $_.AddressFamily -eq "IPv4" } | `
  Select-Object -ExpandProperty IPAddress
netsh interface portproxy add v4tov4 `
  listenport=9000 connectaddress="${HOST_IP}" connectport=9000

2 - How Does It Work

This chapter provides a technical overview of the architecture and internals of Bash Dev Env. It covers the main components, their interactions, and how they work together to provide a seamless installation and configuration experience.

1. Install command

this project consists of one simple command install that will

• load the profile provided in argument
• rotate logs
• execute each install/configure/test scripts (in order including the dependencies of each profile selected scripts)
• recapitulate duration, actions and important information

Some scripts are mandatory and are always executed, no matter what profile chosen:

• _Test - do some mandatory checks before running the process
• _Upgrade (first) - upgrade apt packages
• MandatorySoftwares (second) - softwares mandatory for this whole system to work properly
• _Clean (last) - clean apt, temp files, …

2. Engine

2.1. lib/loadAndCheckConfig.sh - loadAndCheckConfig

The most important function is loadAndCheckConfig from lib/loadAndCheckConfig.sh file.

This function is responsible for:

• loading .env file

  • checks .env file exists, exit on error
  • loads .env file
  • checks validity of each .env variables

• deducing some global variables

  • WSL only
    • WINDOWS_PROFILE_DIR
    • LOCAL_APP_DATA
    • WINDOW_PATH : converted windows PATH variable to linux compatible PATH

• exporting the following variables from .env:

  • USERGROUP
  • USERNAME
  • GIT_USER_MAIL
  • GIT_USERNAME
  • SSH_LOGIN
  • POWERSHELL_BIN

• deducing and export the following variables

  • USERID => computed from USERNAME provided by .env file
  • USERGROUP_ID => computed from USERGROUP provided by .env file
  • BASH_DEV_ENV_ROOT_DIR => <full path to this project directory>
  • IPCONFIG => heavy computation of the right command to use for ipconfig depending environment

• following variables (with default values that could be overridden by .env file)

  • CONF_OVERRIDE_DIRS => defaults to (${BASH_DEV_ENV_ROOT_DIR}/conf_override)
  • LOGS_DIR => defaults to ${BASH_DEV_ENV_ROOT_DIR}/logs
  • PROJECTS_DIR => defaults to ${HOME}/projects
  • BACKUP_DIR => defaults to ${BASH_DEV_ENV_ROOT_DIR}/backup
  • INSTALL_SCRIPTS_ROOT_DIR => defaults to “${BASH_DEV_ENV_ROOT_DIR}”

• setting sudoer without password temporarily

  • create a file in /etc/sudoers.d folder to avoid asking sudo password when it expires
  • create /etc/sudoers.d/bash-dev-env (check refactoring needed section)

• installing and configuring the file ${HOME}/.bash-dev-env

  • the aim of this file is to provide common configuration variables for both ShellZsh and ShellBash
  • the main advantage of this file is that it can be automatically updated without risking to overwrite .bashrc file
  • the variable OVERWRITE_CONFIG_FILES is ignored
  • it provides the following environment variables, among others: PATH, COMPOSER_HOME, AWS_REGION, AWS_PROFILE, SSH_LOGIN, …
  • all these variables can then be reused by all the different script configurations like ssh aliases, Saml2Aws, …
  • this file loads this project .env file so variables like SHOW_FORTUNES and SHOW_MOTD can be taken into account by .bashrc, …

Note: this function has too much responsibilities and has to be refactored (cut in more specialized functions).

2.2. lib/loadAndCheckConfig.sh - loadProfile

This function :

• checks that no files are missing for each script configuration (install, configure, test)
• checks that each script dependency exists
• computes the order to run the scripts depending on CONFIG_LIST order and dependencies of each config script.

Loads the file profile.default.sh if PROFILE is default (-p parameter). Providing CONFIG_LIST array of scripts to load.

3. Libraries

Some of the functions you can find:

• lib/utils/Assert.sh provides utility functions to do some checks.
• Functions::aptInstall use this function in order to be sure to use the correct default parameters it includes retry.
• Functions::aptAddRepository
• getGithubLatestRelease very useful in order to get last release version of a github project
• upgradeGithubRelease
• Assert::wsl
• NetFunctions::addHost add host in /etc/hosts and windows hosts file if wsl (backup file before updates)
• validator functions
• Version::checkMinimal and Version::compare: version comparison function
• log and logRotate functions
• backup function
• installFile/installDir install file or dir doing backup before and OVERRIDE_CONF variable aware
• gitPullIfNoChanges/gitCloneOrPullIfNoChanges

4. Configurations

Configurations are folders in the scripts directory. when you create a new configuration, please be sure it sources the file lib/common.sh, as it initializes correctly the environment, load the main libraries, load the profile and set bash flags like errexit and pipefail.

Configuration should have the following files:

• install
• configure
• test

It could have also the following optional files:

• fortunes
• dependencies
• breakOnConfigFailure if present and config is failing, the whole process is stopped
• breakOnTestFailure if present and test is failing, the whole process is stopped

3 - How to Contribute

1. Formatting rules

before committing, be sure that pre-commit hooks are installed in the repository. It will ensure during commit to:

• format the files
• check for errors

2. How to prepare a new image

Here the solution to test this solution without impacting your current distribution or in order to generate a wsl distribution

2.1. Prepare distribution

• Download ubuntu distribution archive and unpack it

Remove-Item alias:curl
curl.exe -L -o ubuntu-2004.appx https://aka.ms/wslubuntu2004
Rename-Item ./ubuntu-2004.appx ./ubuntu-2004.zip
Expand-Archive ./ubuntu-2004.zip ./Ubuntu-2004

• If ubuntu distribution is not already installed on your computer, just run

.\Ubuntu-2004\ubuntu.exe

• Else you have to import tar file

2 Optional steps: you can manually extract ./Ubuntu-2004/install.tar.gz to ./Ubuntu-2004/install.tar from 7Zip App.

(optional) first install 7zip for powershell using powershell as Administrator

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
Set-PSRepository -Name 'PSGallery' -SourceLocation "https://www.powershellgallery.com/api/v2" -InstallationPolicy Trusted
Install-Module -Name 7Zip4PowerShell -Force

• (optional) Extract ./Ubuntu-2004/install.tar.gz to ./Ubuntu-2004/install.tar

Expand-Archive ./Ubuntu-2004/install.tar.gz ./Ubuntu-2004/install.tar
Expand-7Zip -ArchiveFileName ./Ubuntu-2004/install.tar.gz -TargetPath ./Ubuntu-2004

• Import and run the distribution

wsl --import UbuntuTest .\UbuntuTest ./Ubuntu-2004/install.tar --version 2
wsl -d UbuntuTest

• As root create wsl user and make wsl user as default login

useradd -m wslTest --create-home
chsh -s "$(which bash)" wslTest
# add user to group sudo
usermod -a -G sudo wslTest
passwd wslTest

• Finally launching distro will always launch terminal using root user

to use wsl as default, I suggest to create a terminal profile with the following command wsl.exe -d UbuntuTest -u wslTest

2.2. install the project

Follow Install instruction

3. Prepare a tar image for sharing

Follow Install instruction

Ensure you are using wsl user login name instead of wslTest.

And install the project using this command

sudo ./install -p default --prepare-export

This will remove any sensitive files at the end of the process.

3.1. export the image

export the wsl image

wsl --shutdown
wsl --export WslDevEnv WslDevEnv.tar
wsl.exe gzip /mnt/c/programs/WslDevEnv.tar

3.2. import the image

mkdir C:\Programs\WslDevEnv
wsl.exe --import WslDevEnv C:\Programs\WslDevEnv C:\Programs\WslDevEnv.tar.gz

3.3. run again the installation

Follow Install instruction it will build docker images and copy missing files on the new computer