Setup

You will need to perform these setup steps from an internet-connected x86_64 workstation with a Linux-based operating system.

The system will need a package manager and you will need enough access to install packages.

Install Bash

You will need bash (v5.x.x) installed on your workstation. This is likely already done if you have a common, modern Linux distribution.

You can check if bash is already installed by opening up a terminal emulator and running this command:

bash --version

If bash is installed, you should see something like this:

GNU bash, version 5.3.3(1)-release (x86_64-pc-linux-gnu)
Copyright (C) 2025 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

This is free software; you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Note the version number on the first line. It should be a version 5.x.x number. The minor version (after the first dot in the version number) should not matter for this workshop.

If bash is not installed, you should see an error message that indicates that bash is not a utility available in your path. If so, you will need to install it. Most Linux distributions package the bash utility under the "bash" package name.

Install Git

In order to pull down the source code from the repository that you will be working out of, you will also need the git utility.

You can check if git (v2.x.x) is installed by running the following command on your workstation.

git --version

If installed, this command should return something like this:

git version 2.51.0

Note the version number. It should be version 2. These lab instructions may work with other versions, but have only been tested with v2. The minor and patch version (after the first dot in the version number) should not matter for this workshop.

If git is not installed, you should see an error message that indicates that git is not a utility available in your path. If so, you will need to install it. Most Linux distributions package the git utility under the "git" package name.

You can also consult the install instructions provided by the upstream vendor.

Install Shellcheck

The command-line utility we will be wrapping is shellcheck which is a bash script linter.

There are several ways to install this utility listed in the Shellcheck README.

However, if you just want to temporarily drop it directly into /usr/local/bin/ you can simply run this:

failure_detected=false; \
[[ "$PATH" =~ /usr/local/bin ]] || \
  { echo "[FAIL] /usr/local/bin not found in shell \$PATH."; failure_detected=true; }; \
for dep in sudo tar curl chmod mv rm; do \
  hash "$dep" || \
  { \
    failure_detected=true; \
    echo "[FAIL] $dep not found in shell \$PATH."; \
  }; \
done; \
if ! $failure_detected; then \
  curl \
    -fsSL \
    -o "${HOME}/shellcheck.tar.gz" \
    https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz \
  && echo "[INFO] Extracting shellcheck.tar.gz into home directory (${HOME}/shellcheck-v0.11.0/)..." \
  && tar -vxf "${HOME}/shellcheck.tar.gz" -C "${HOME}" \
  && sudo mv "${HOME}/shellcheck-v0.11.0/shellcheck" /usr/local/bin/shellcheck \
  && sudo chmod 0755 /usr/local/bin/shellcheck \
  && echo "[INFO] Cleaning up unneeded shellcheck v0.11.0 install artifacts..." \
  && rm -vfr "${HOME}/shellcheck-v0.11.0/" \
  && rm -vf "${HOME}/shellcheck.tar.gz" \
  && echo "[INFO] Validating shellcheck install..." \
  && shellcheck --version; \
fi

If installed, you should see something like this at the end of the output:

[INFO] Validating shellcheck install...
ShellCheck - shell script analysis tool
version: 0.11.0
license: GNU General Public License, version 3
website: https://www.shellcheck.net

This workshop has been tested with this specific version of shellcheck, so for best results, use this exact version (or close to it).

Install Lefthook

In order to manage your git hooks, you will need to install the lefthook statically-compiled golang binary.

There are several ways to install this utility listed on the Lefthook installation page.

However, if you just want to temporarily drop it directly into /usr/local/bin/ you can simply run this:

failure_detected=false; \
for dep in sudo curl chmod; do \
  hash "$dep" || \
  { \
    failure_detected=true; \
    echo "$dep not found in shell \$PATH."; \
  }; \
done; \
[[ $failure_detected ]] \
&& sudo \
     curl \
       -fsSL \
       -o /usr/local/bin/lefthook \
       https://github.com/evilmartians/lefthook/releases/download/v1.13.4/lefthook_1.13.4_Linux_x86_64 \
&& sudo chmod 0755 /usr/local/bin/lefthook \
&& echo "Lefthook version: $(lefthook version)";

If installed, this command should return something like this:

Lefthook version: 1.13.4

This workshop has been tested with this specific version of lefthook, so for best results, use this exact version (or close to it).

Install Docker & Compose

While this workshop is possible (in theory) with both docker and podman, using these instructions with podman is untested. Additionally, you will also need to install podman-compose as a separate utility if you decide to go the podman route. The podman-compose install options are listed in the podman-compose README.

If using podman instead of docker, for the rest of this workshop replace docker with podman anywhere that docker is referenced.

In order to call your wrapper script and shellcheck in a consistent manner without requiring your users to keep specific bash or shellcheck versions installed on their local machine, we will be baking them both into a container image using docker.

For installing docker, you have some options. The most straight forward is usually to use your distribution's installation instructions; however, it should be noted that individual linux distribution maintainers do not always ship the most up-to-date version of docker in their repositories. For this workshop, that is fine. We are not leveraging any cutting edge docker or docker compose features here.

If you want to use your distribution's official docker install instructions, here is a list of install commands and links to more in-depth install instructions for some common desktop Linux distribution families:

• Debian-based: sudo apt-get install docker.io (Source)
• Arch-based: sudo pacman -S docker (Source)
• EL-based: sudo dnf install docker-cli containerd docker-compose (Source)

If you want to use the upstream software vendor's repositories, follow these instructions on Docker's website.

Regardless of distribution, you will need to ensure that your user is added to the docker group.

getent group docker

This should return the "docker" entry from /etc/group and your username should be at the end of the line, like so:

docker:x:dockergroupidhere:yourusernamehere

If getent returns nothing, there is no docker group. If you doubt this, you can confirm by manually inspecting /etc/group.

{ cat /etc/group | grep 'docker:'; } || cat /etc/group

If the docker group entry is empty after the last colon, or your username is not listed in the comma-separated user list, you will need to append (-a) "docker" to your user's list of groups (-G) with the usermod utility.

sudo usermod -aG docker "${USER}" \
&& getent group docker

If you had to add your username to the "docker" group, you will also need to logout and log back in for this to take effect.

Additionally, if you just installed docker, you will either need to activate the service, or ensure that it is setup to activate on boot and then reboot.

Here is how to start, enable (start on boot), and check the status of the service on a Linux distribution that uses systemd as its init system.

sudo systemctl enable --now docker.service \
&& sudo systemctl status docker.service

The service should report back "active (running)" and enabled if properly working. If not, try a reboot.

docker.service - Docker Application Container Engine Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: disabled) Active: active (running) since...

Once enabled (and started), try running the Docker-provided hello-world container image.

docker run hello-world

If the Docker service is working properly, you should see output similar to this from the container:

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

If you do not see this, try rebooting if you have not done so already. When docker is first installed it creates a bunch of firewall rules and on some distributions it is known to require a reboot to work properly. So, if it still does not work after you have done the install, added your user to the right group, and enabled the service... when in doubt reboot it out.

Don't Be Like Robin

Clone Git Repo

Next, you will use the git utility to retrieve the source code that you will be working with today. You can copy and paste the command below to create a directory called "bash-programming" in your current user's home directory. This directory will contain the source code you will be working with.

cd "$HOME" \
&& git clone https://gitlab.com/codrcodz/pipelines-as-a-service.git \
&& cd pipelines-as-a-service \
&& { ls README.md && echo 'It worked! :-)'; } || echo 'It did NOT work! :-('

The last line should look something like this:

It worked! :-)

If you do not see that line, something likely did not work properly; read any error messages.

It did NOT work! :-(

Select a Text Editor

If you already have a text editor installed on your workstation that you are comfortable with, just use that.

Try new editors at your own risk. This is not a vim workshop...

First Time Vim Users

If you have a desktop environment (DE) installed as part of your Linux distribution, you most likely already have a graphical text editor installed.

If this is your first time using a text editor, start with the graphical one your Linux distribution ships with.

• The KDE DE team maintains kate
• The Gnome DE team maintains gedit
• The XFCE DE team maintains mousepad
• The Linux Mint distribution team (maintainers of the Cinnamon DE) maintain xed
• If you are not sure what DE your distribution is using, search for "text editor" in your application menu

Graphical text editors usually do not require users to know any keyboard shortcuts. Things like saving files, exiting the editor, and other common functions can all be done with the mouse/trackpad.