Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dragondive/whistle

whistle is a utility to automatically download Ubuntu WSL images, create new WSL2 instances and provision them.
https://github.com/dragondive/whistle

automation bash-script powershell-script sysadmin-scripts windows wsl wsl2

Last synced: about 1 month ago
JSON representation

whistle is a utility to automatically download Ubuntu WSL images, create new WSL2 instances and provision them.

Host: GitHub
URL: https://github.com/dragondive/whistle
Owner: dragondive
License: gpl-3.0
Created: 2024-08-23T11:13:49.000Z (5 months ago)
Default Branch: main
Last Pushed: 2024-11-15T12:02:28.000Z (about 2 months ago)
Last Synced: 2024-11-28T23:31:23.862Z (about 1 month ago)
Topics: automation, bash-script, powershell-script, sysadmin-scripts, windows, wsl, wsl2
Language: Shell
Homepage:
Size: 39.1 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.rst

Awesome Lists containing this project

README

Whistle
=======

``whistle`` is a utility to automatically download Ubuntu WSL images, create new WSL2
instances and provision them.

.. contents:: **Outline**

How to use
----------

1. Download this repository as a zip file and extract it into any directory on your
local machine.

2. Open a powershell terminal and navigate to that directory.

.. pull-quote:: \:one: **ONE-TIME SETUP**

Install WSL with the following command, then restart your computer.

.. code-block:: terminal

wsl --install --no-distribution

3. Run the following command:

.. code-block:: powershell

PowerShell -ExecutionPolicy Bypass -File .\whistle.ps1 --WslDistroName whistleblower

This creates a new WSL2 instance of the default Linux flavour and release with only
the core setup bundles installed. See the `Parameters`_ section below to install
additional optional bundles and for other customizations.

.. pull-quote:: \:bangbang: **IMPORTANT**

The script also creates a standard user on the WSL2 instance. By default, the
username and password are the same as the instance name.

.. pull-quote:: \:bulb: **TIP**

To create another instance, run the command again with a different instance name.

.. pull-quote:: \:drum: **ATTENTION**

PowerShell's `execution policy `_
prevents execution of unsigned scripts. The ``-ExecutionPolicy Bypass`` in the
above command bypasses it to enable ``whistle.ps1`` to be executed. I do not
currently want to buy a code-signing certificate. However, I will easily change
my mind if I receive enough sponsorship. See the `Sponsoring`_ section for
sponsoring information.

Parameters
----------

.. list-table:: Parameters
:header-rows: 1

* - **⠀⠀⠀Parameter⠀⠀⠀**
- **Description**
- **Examples**
- **Default**
- **Notes**
* - ``-WslDistroName``
- Name for your new WSL2 instance.
- ``whistleblower``, ``heavens-arena``
- ``whistleblower``
-
* - ``-ReleaseName``
- Ubuntu release name.
- ``noble``, ``jammy``
- ``noble``
- Available releases at https://cloud-images.ubuntu.com/wsl/.
* - ``-ReleaseTag``
- Release tag of the WSL2 image to download.
- ``current``, ``20241008``
- ``current``
- Available tags inside the chosen release directory at the above page.
* - ``-ReleaseArch``
- Architecture of the WSL2 image.
- ``amd64``, ``arm64``
- ``amd64``
-
* - ``-SetupArgs``
- Arguments for the setup script ``whistle.bash``.
- ``"-h"``, ``"-b python3"``, ``"-u dragondive -b copy-ssh-keys"``
- ``""``
- This needs to be enclosed in double quotes.
Run with ``"'-h'"`` for the full description of the supported arguments.

Contributor Documentation
-------------------------

``whistle`` consists of two scripts:

1. The powershell script ``whistle.ps1`` that downloads the WSL2 image and creates an
instance of it.
2. The bash script ``whistle.bash`` that provisions the installed WSL2 instance.

These scripts are further described in the below sections.

powershell script ``whistle.ps1``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This script performs the following main operations:

1. Download the user-specified WSL2 image: As an optimization, the images are cached to
a standard location which avoids redownloading when the script is run multiple times.
2. Import the WSL2 image to create a new instance of it.
3. Install VS Code: It is more convenient to install it on Windows and further configure
it from WSL2 than installing it directly inside WSL2.
4. Run the provisioning script ``whistle.bash`` inside the newly created WSL2 instance.

bash script ``whistle.bash``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This script performs various installation and configuration steps. It first executes as
the root user and then as a standard user. While running as the root user, it also
creates the standard user.

The installation and configuration steps are organized into setup bundles. Setup bundles
are of two types:

1. **core bundles**: These are always executed as they perform essential installation
and configuration.
2. **optional bundles**: These are executed only if requested.

How to define a new setup bundle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section describes the steps required to define a new setup bundle, which is given
the hypothetical name ``watchdog`` for clarity of understanding. Perform the following
modifications in the ``whistle.bash`` file:

1. Decide if ``watchdog`` is a core bundle or an optional bundle. Accordingly, add an
item to the ``EXECUTE_BUNDLE`` associative array.

*Core bundle*

.. code-block:: bash
:caption: watchdog is a core bundle

EXECUTE_BUNDLE=(
...
[watchdog]=1
)

*Optional bundle*

.. code-block:: bash
:caption: watchdog is an optional bundle

EXECUTE_BUNDLE=(
...
[watchdog]=0
)

2. Determine if the ``watchdog`` bundle should be executed as the root user or as
the standard user. This determines the placement of its installation and
configuration steps block (described in the next step). You may also execute it in
two parts, first as the root user and then as the standard user.

* To execute it as the root user, the installation and configuration block needs to
be inside the following ``if`` ... ``fi`` block:

.. code-block:: bash
:caption: Execute watchdog as the root user

if [[ $EUID -eq 0 ]]; then
...
# watchdog's installation and configuration block (described in the next step)
# needs to go here.
...
fi

* To execute it as the standard user, the installation and configuration block needs
to be outside *and* after the above-mentioned ``if`` ... ``fi`` block.

.. pull-quote:: \:bulb: **TIP**

To preserve any environment variables when the script switches from the root
user to the standard user, append it to the ``--preserve-env`` argument of the
``exec sudo`` command:

.. code-block:: bash
:caption: preserving environment variables when switching to the standard user
:highlight-lines: 2

echo "Switching to the standard user for further configuration..."
exec sudo \
--preserve-env=USERNAME,PATH,WSL_DISTRO_NAME \
--login \
--user "$DEFAULT_USER" \
"$(realpath $0)" "${ARGUMENTS[@]}"

3. Define the installation and configuration steps for ``watchdog`` in
an ``if`` ... ``fi`` block:

.. code-block:: bash
:caption: installation and configuration steps for the watchdog bundle

if [ "${EXECUTE_BUNDLE[watchdog]}" -eq 1 ]; then
echo "Installing watchdog..."

# Add installation and configuration steps for watchdog here
sudo apt-get install -yq example-watchdog
export PATH="$PATH:/usr/bin/example-watchdog" | tee -a /home/$DEFAULT_USER/.profile
...
fi

* **VS Code extensions** (optional): Suitable VS Code extensions may be
specified for installation in the installation and configuration block:

.. code-block:: bash
:caption: Specifying VS Code extensions

VSCODE_EXTENSIONS+=(\
"whistleblower.watchdog.bark", \
"whistleblower.watchdog.bite" \
)

4. Update the ``display_help()`` function mentioning the ``watchdog`` setup bundle,
with additional explanation if necessary.

Sponsoring
----------

If you like ``whistle`` and you are doing well in life, you can sponsor it. You can
make a recurring or a one-time contribution with any amount of your choice. My finances
are thankfully in a reasonably healthy state, so the sponsorship is for you to feel
good about supporting what you found useful.

.. pull-quote:: \:pray: **CREDIT**

The text of the above message is inspired by `agadmator's Excellent Subscribers video `_.

**Sponsoring options**

Sponsor using one of the following options:

.. raw:: html

You can also sponsor directly with Unified Payments Interface (UPI) :fire:, if you are
Indian :india: or in a country that supports remittance by UPI to India. Scan the below
QR code or use my UPI id ``apai@upi``.

.. raw:: html