Arch Avisto WSL

This project contains the sources and the documentation to ship updates of the Arch Avisto image.

For documentation about the installation as a consumer.

Setup

Pre-commit

This project uses pre-commit tool documentation.

The goal is to run scripts or tasks (called hooks) on a commit basis (e.g. linting, small checks, documentation as code, etc.).

For this purpose, pre-commit will execute all the hooks declared in in then .pre-commit-config.yaml configuration file.

1. Install the tool. pip install pre-commit
2. Install the git hook. pre-commit install
3. Verify it is working by running pre-commit hooks. pre-commit run --all-files

Golang

The bootscript is written in Golang

Introduction

History

The aim of Arch Avisto was to deliver a container solution (docker in our case) out-of-the box for the teams without relaying on Docker Desktop, for licence reasons. Indeed, its installation on WSL was error prone and time consuming.

Arch Avisto is based on Arch Linux, and its first version was born using ArchWSL.

Architecture

There are two users in this image

• arch is the normal user. This user will be renamed.
• login is the default user on the first launch. Its job is to launch the bootscript.

They are a few important files on the Arch Avisto WSL image.

Static files:

• /home/arch is the home of the default user. It holds .zshrc and .config/starship.toml as basic configuration
• /opt/prep.sh is a script to prepare the image (clearing history and caches). It should be manually used before exporting.
• /usr/bin/slogin is the shell of the login user. This shell is responsible to download and run bootscript, then start the bash script generated by bootscript

Other files:

• /opt/startup/bootscript is the binary executed by slogin on startup, it will be fetched from the Github release and is responsible to prompt the user for the packages he wants, his username, etc.
• /opt/startup/script.sh is the script generated by the binary bootscript and executed by slogin, it contains all bash commands that will set up the images

ⓘ Note The bootscript will try to fetch and parse the file packages.json located in the Github repository in order to prompt the user the latest packages without having to rebuild an image

CI/CD

Github actions are responsible of releasing the bootscript as an asset.

Step-by-step releases guide

Arch Avisto image

When the changes you want to make are on the image itself:

Before starting be sure you run the latest WSL version (see doc).
Also install 7-zip.

1. Use the documentation to import the image, then login using wsl -u arch -d <distro-name>
2. Do your changes
3. Change the ARCHAVISTO_VERSION in the slogin script to the new version and copy the content of the script in /opt/startup/slogin
4. Prep the image by running source /opt/prep.sh
5. Open a Powershell
6. Shutdown wsl with wsl --terminate <distro-name>
7. Export the distribution as a compressed archive (see the command below)
8. Upload it to the SharePoint (step 1)
9. Make at least 1 person test it
10. Change SharePoint link on the documentation (step 2) to point to the new version
11. Update the CHANGELOG.md with the new version and the changes

# Export the distribution as a compressed archive
wsl --export test .\arch_avisto_v2.1.5.tar
& "C:\Program Files\7-Zip\7z.exe" a .\arch_avisto_v2.1.5.tar.gz .\arch_avisto_v2.1.5.tar

Bootscript

First, follow all the Avisto guidelines for a new feature (new issue -> create PR -> review -> merge)

Next, here are the steps to test your image:

1. Update the bootscriptVersion in the main.go (usually located line 15)
2. Check that the pipeline pass once you committed your changes
3. Use the documentation to import the image, then login using wsl -u root -d <distro-name>
4. Wait for the pipeline to pass
5. Modify the RELEASE variable in the /opt/startup/slogin to fetch your version of the bootscript
6. Run su login and verify all your changes are working properly
7. Update the CHANGELOG.md with the new version and the changes
8. If everything is to your liking you can unregister the wsl distro (using wsl --unregister <distro-name>), then ask someone to review your PR!
9. Once happy, merge the PR and tag the merge commit on main, it'll automatically create a new release

When someone changes the bootscript, there is no need to either release a new Arch Avisto image nor to redownload the tar for the new bootscrip to be used.

---

Recreate Arch image from scratch

Base Instructions

Distribution installation

Follow this tutorial.

User creation

Create 2 users: arch and login useradd -m arch (to create a home) and useradd login. Also add both users to the wheel group so they can use sudo (usermod -aG wheel arch and usermod -aG wheel login).

Login set up

Now login as the arch user su arch && cd ~.

Install paru using the documentation (do it in /tmp or clean folder afterwards).

Create a /opt/startup directory and put the slogin script found on the arch avisto repo.

Note

Don't forget to give the ownership of the /opt/startup directory to the login user.

Once this is done, time to change the /etc/passwd file to modify the default shell of the login user to /opt/startup/slogin, do it by running sudo chsh -s /opt/startup/slogin login and modify the default user to be the login user in the /etc/wsl.conf file.

[user]
default=login

[boot]
systemd=true

Warning

From now on, don't forget to start the distribution using wsl -d <distro> -u arch to avoid going through the installation script.

Distribution customization

Installing docker

To install docker, simply paru -S docker then sudo systemctl enable docker and sudo systemctl start docker.

Note

Don't forget to add the user to the docker group sudo usermod -aG docker arch.

Fastfetch

1. Install fastfetch paru -S fastfetch.
2. Create the logo using jp2a --width=45 --colors --color-depth=8 logo\ Avisto.png --chars=' ###' command with the logo you can find here.
3. Create the directory ~/.config/fastfetch and paste the logo in it.
4. Paste the following content in ~/.config/fastfetch/config.jsonc.

{
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json",
  "modules": [
    "title",
    "separator",
    "os",
    "host",
    "kernel",
    "uptime",
    "packages",
    "shell",
    "display",
    "de",
    "wm",
    "terminal",
    "cpu",
    "gpu",
    "memory",
    "swap",
    "disk",
    "localip",
    "battery",
    "poweradapter",
    "break",
    "colors"
  ],
  "logo": {
    "type": "auto",
    "source": "$HOME/.config/fastfetch/avisto-logo"
  }
}

Shells

We provide minimal configuration for all shells proposed in the installation script first install all shells ( paru -S fish bash zsh).

Zsh

if command -v direnv >/dev/null 2>&1; then
  eval "$(direnv hook zsh)"
fi
if command -v starship >/dev/null 2>&1; then
  eval "$(starship init zsh)"
fi

echo; fastfetch; echo;

Bash

Paste this in the ~/.bash_profile.

if command -v direnv >/dev/null 2>&1; then
  eval "$(direnv hook bash)"
fi
if command -v starship >/dev/null 2>&1; then
  eval "$(starship init bash)"
fi

echo; fastfetch; echo;

Fish

Paste the following in the ~/.config/fish/config.fish

if command -v starship > /dev/null 2>&1
    starship init fish | source
end
if command -v direnv > /dev/null 2>&1
    direnv hook fish | source
end

echo; fastfetch; echo;

Generate locale

To generate locale, modify the /etc/locale.gen and uncomment your desired locale, then run sudo locale-gen (for instance current image uses en_US.UTF-8 UTF-8).

Clearing cache

Note

We advise clearing all cache and shell history before shipping, source that script to do so.

#! /usr/bin/env bash
paru --noconfirm -R $(paru -Qtdq) || true
paru --noconfirm -Sc || true
rm -rf ~/.cargo
rm -rf ~/.cache
sudo rm -rf /var/cache
sudo rm -rf /var/log
echo "" > ~/.bash_history
history -c