olge404.unix

This ansible collection is useful to streamline and ease the automated installation and configuration of various software packages on unix-like operating systems (e.g. ubuntu, debian, linuxmint, etc.).

Usage and docs

To install this collection, run:

ansible-galaxy collection install olge404.unix

Documentation for this collection and each role can be found on GitHub or on ansible-galaxy hub.

Development

The code is hosted on Github and CI is done on GitHub actions. The CI uses various shell scripts to perform installation, configuration and tests during a pipeline run. Each shell script provides a help function that describes how the script can be used. The help function can be called by providing either the -h or --help argument when running a script. For example:

scripts/python3-venv.sh --help
scripts/build-container.sh -h

Prerequisites

To develop roles for this collection, some tools are necessary. Those are:

• ansible
• molecule (+ drivers for docker and vagrant)
• docker
• vagrant
• virtualbox
• yq

To setup the virtual environment for python and install ansible, molecule and the required drivers in it, run:

scripts/python3-venv.sh

Next, activate the python virtualenv in your shell and install this collection:

source .venv/bin/activate
ansible-galaxy collection install --force olge404.unix

Now run the prerequisites playbook (depending on your machine) to install docker, vagrant, virtualbox and yq:

# For Linux Mint 22
ansible-playbook linux-mint-22.yml

To test that all prerequisites are fullfilled, run:

# Run sanity tests for the collection
scripts/ansible-test-sanity.sh

# Run tests using the docker driver for molecule
scripts/molecule-test.sh apt

# Run tests using the vagrant driver for molecule
scripts/molecule-test.sh docker_ce

If those commands work, you are good to go.

Scope

Each role should serve one purpose like "install a package on a debian-like distro". The goal is to keep each role as simple and concise as possible to ensure it can be tested properly and that it does what you would expect from it by reading its README file.

Good examples are roles like apt or vscode_extensions. They are used for basic tasks and you might think "do I even need a role for that?" and the answer is: YES! Using tested, reliable building blocks that adhere to best practices is a key element to build any reliable automation and that is what this collection was made for.

Tests platforms

Roles in this collection are tested on various unix-like operating systems (test platforms). Testing is done by leveraging molecule as test framework and docker or vagrant as driver to launch these test platforms. This ensures predictable test results by creating test infrastructure on-demand in a simple and repeatable manner.

Testing with docker

Because we are using docker for some tests, we need a container image for each platform we want to run our tests on. The Dockerfiles for these container images can be found in the .molecule/platforms dir. The docker-build.sh script should be used to build, tag and push container images to dockerhub (if you need to build them manually). The CI will build and push all container images at least once per week (at midnight every Monday). The container images are referenced in the molecule.yml file of a role to be used during molecule tests.

All test platforms need to be prepared to work with ansible and molecule. This includes:

• Installing the python3, sudo and ca-certificates packages
• Creating a non-root user to perform tests with
• Enable passwordless sudo for the non-root user

See the Dockerfile for Ubuntu 24.04 as an example on how to prepare a test platform for molecule.

Testing with vagrant

Sometimes you need a full fledged virtual machine (VM) to test roles properly (e.g. because they rely on software that containers are finicky with or are not ideal for). In those cases, vagrant and virtualbox should be used to spin up VMs on-demand to use as test platforms for molecule.

VMs that are launched with vagrant are called "boxes" and we don't build custom boxes for this repository (at the moment). We use pre-build bento boxes that are ready to be used as test platforms for molecule with vagrant.

Checkout the molecule + vagrant setup to test the docker_ce role to see how this works.

NOTE: Docker should be used to launch test platforms wherever possible, because container images are faster and easier to work with than VMs.

Changelog

All notable changes to this collection have to be listed in the changelog.md file and have to follow semantic versioning.

The changelog.md file adheres to the conventions listed on keepachangelog.com.

Here is a quick overview:

Guiding Principles
    Changelogs are for humans, not machines.
    There should be an entry for every single version.
    The same types of changes should be grouped.
    Versions and sections should be linkable.
    The latest version comes first.
    The release date of each version is displayed.
    Mention whether you follow Semantic Versioning.

Types of changes
    [Added] for new features.
    [Changed] for changes in existing functionality.
    [Deprecated] for soon-to-be removed features.
    [Removed] for now removed features.
    [Fixed] for any bug fixes.
    [Security] in case of vulnerabilities.

Keep an [UNRELEASED] section at the top to track upcoming changes. This serves two purposes:
    People can see what changes they might expect in upcoming releases
    At release time, you can move the [UNRELEASED] section changes into a new release version section.

Release a new version

The release.yml pipeline is used to test, build and publish a new version of this collection to ansible-galaxy hub if a release-tag is pushed.

Before attempting to release a new version, update the version field in the galaxy.yml file. The release pipeline will check if the version of the release-tag matches the version field in the galaxy.yml file and will fail, if it doesn't match. It will also fail if the version you are trying to release already exists on ansible-galaxy hub.

If you forgot to update the version field in the galaxy.yml file, but already pushed a release-tag and the release pipeline fails, you have to:

• Update the version in the galaxy.yml file and push it
• Delete the failed release-tag locally and remote
• Create and push a new annotated release-tag to retry the release

Here is a cheatsheet on how to list, delete and create new git tags to perform a release. The release pipeline will be triggered if a tag is pushed that matches release-X.Y.Z.

# Get version from galaxy.yml file
RELEASE_VERSION=$(yq .version galaxy.yml)

# List all tags
git tag

# Create and push a new tag
git tag -a release-$RELEASE_VERSION -m "Release version $RELEASE_VERSION"
git push origin release-$RELEASE_VERSION

# Delete tag locally and remote (if release pipeline failed)
git tag -d release-$RELEASE_VERSION
git push origin --delete release-$RELEASE_VERSION