Xebis Ansible Collection

A collection of Xebis shared Ansible roles.

The project is under active development.

Table of Contents

• Features
  • Ansible Roles
  • Supported OS
• Installation and Configuration
• Usage
  • Caveats
• Contributing
  • Development
  • Testing
    • Test at Docker Container
• Credits and Acknowledgments
• Copyright and Licensing
• Changelog and News
• Notes and References
  • Dependencies
  • Recommendations
  • Suggestions
  • Further Reading

Features

Ansible Roles

Role	Description	Documentation	Dependencies
xebis.ansible.system	Well maintained operating system	Updates and upgrades deb packages including autoremove and autoclean, reboots the system (when necessary), provides Reboot machine handler
xebis.ansible.firewall	Extensible nftables firewall	Installs nftables and sets up basic extensible nftables chains and rules, provides Revalidate and reload nftables and Reload nftables handlers, see Firewall role README.md for usage, configuration, and examples	xebis.ansible.system
xebis.ansible.fail2ban	Fail2ban service	Installs fail2ban and sets it up as a systemd service	xebis.ansible.system xebis.ansible.firewall
xebis.ansible.iam	IAM	Creates user groups and users as regular users or admins, their public SSH keys, disables password remote logins, provides Restart sshd handler, see IAM role README.md for usage, configuration, and examples	xebis.ansible.system xebis.ansible.firewall xebis.ansible.fail2ban
xebis.ansible.bash	Extensible Bash	Installs ~/.bash_aliases and sets up basic extensible Bash aliases, see Bash role README.md for usage, configuration, and examples	xebis.ansible.system
xebis.ansible.admin	Administration essentials	Installs and sets up at, curl, htop, mc, screen	xebis.ansible.system
xebis.ansible.snapd	Snap daemon	Installs snapd and sets it up	xebis.ansible.system
xebis.ansible.starship	Starship CLI prompt	Installs starship and sets up improved PowerLine configuration	xebis.ansible.snapd
xebis.ansible.docker	Docker essentials	Installs docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, docker-compose-plugin from Docker apt repository, sets up nftables firewall for Docker ⚠ firewall rules are not production ready, and prunes builder cache, containers, images including non-dangling, networks and volumes	xebis.ansible.system xebis.ansible.firewall
xebis.ansible.flatpak	Well maintained Flatpak	Updates and upgrades Flatpak packages including removing unused ones	xebis.ansible.system
xebis.ansible.physical	Physical machine essentials	Installs hwinfo, sets up to show GRUB menu with 3s timeout, and sets up /tmp in tmpfs, provides Update GRUB configuration handler	xebis.ansible.system
xebis.ansible.engineering	Engineering essentials	Installs and sets up direnv	xebis.ansible.system
xebis.ansible.kde	KDE essentials	Installs krusader (including recommended dependencies kdiff3, kget, and krename), kwin-bismuth, sets up nftables firewall for KDE, and provides Plasma Reload desktop icon	xebis.ansible.system xebis.ansible.firewall
xebis.ansible.multimedia	Multimedia essentials	Installs audacity, darktable, digikam, exfat-fuse, exfatprogs, gimp, and rawtherapee	xebis.ansible.system
xebis.ansible.slack	Slack	Installs slack	xebis.ansible.snapd
xebis.ansible.thunderbird	Thunderbird	Installs thunderbird and sets up nftables firewall for Thunderbird	xebis.ansible.system xebis.ansible.firewall
xebis.ansible.obsidian	Obsidian	Installs obsidian	xebis.ansible.snapd
xebis.ansible.xmind	Xmind	Installs xmind	xebis.ansible.flatpak
xebis.ansible.steam	Steam	Installs steam-installer	xebis.ansible.system xebis.ansible.firewall
xebis.ansible.openttd	OpenTTD (transport simulation game)	Installs OpenTTD including openttd-opensfx	xebis.ansible.system
xebis.ansible.widelands	Widelands (real-time strategy game)	Installs Widelands and setups firewall	xebis.ansible.system xebis.ansible.firewall xebis.ansible.flatpak

Supported OS

Ubuntu Server 22.04 and Kubuntu 22.04 are supported.

Installation and Configuration

Install the collection using ansible-galaxy collection install [email protected]/xebis/xebis-ansible-collection.git, or you can use requirements.yml and install it with ansible-galaxy install -r requirements.yml:

collections:
  - name: git+https://github.com/xebis/xebis-ansible-collection.git,main

Usage

In an Ansible playbook:

  roles:
    - role: xebis.ansible.role

• IAM usage, configuration, and examples
• Firewall usage, configuration, and examples

Caveats

When a role is removed from a playbook, actions performed by the role are not reverted. This might lead to security risks and unexpected results, for example:

• xebis.ansible.iam might leave users and their access on the system
• xebis.ansible.firewall leaves firewall installed on the system
• a role with dependency on xebis.ansible.firewall might leave unwanted firewall rules on the system

Contributing

Please read CONTRIBUTING for details on our code of conduct, and the process for submitting merge requests to us.

Development

Local collection testing:

ansible-galaxy collection build --force # Outputs collection build file
ansible-galaxy collection install --force /path/to/xebis-ansible-collection/xebis-ansible-version.tar.gz

Testing

• Git hooks check a lot of things for you, including running automated tests scripts/test full

• Make sure all scripts/*, git hooks, and GitLab pipelines work as expected, testing checklist:

• scripts/* scripts - covered by unit tests tests/*

  • scripts/bootstrap
  • scripts/pre-commit
  • scripts/pre-push
  • scripts/setup
  • scripts/test
  • scripts/update

• Local working directory

  • git commit runs pre-commit hook-type commit-msg and scripts/pre-commit
  • git merge
    • Fast-forward shouldn't run any hooks or scripts
    • Automatically resolved merge commit runs pre-commit hook-type commit-msg and scripts/pre-commit
    • Manually resolved merge commit runs pre-commit hook-type commit-msg and scripts/pre-commit
  • git push runs scripts/pre-push
  • pre-commit run -a --hook-stage manual runs all hooks and check-hooks-apply hook fails on check-symlinks and forbid-binary

• GitLab CI

  • Commit in non-main branch runs validate:lint and validate:test-full
  • Merge to main branch runs validate:lint, validate:test-full, and release:release
    • With a new feat or fix commit releases a new version
    • Without a new feature or fix commit does not release a new version
  • Scheduled (nightly) pipeline runs validate:lint and validate:test-nightly

Test at Docker Container

To test your changes in a different environment, you might try to run a Docker container and test it from there.

Run a disposal Docker container:

• sudo docker run -it --rm -v "$(pwd)":/xebis-ansible-collection alpine:latest
• sudo docker run -it --rm -v "$(pwd)":/xebis-ansible-collection --entrypoint sh node:alpine

In the container:

cd xebis-ansible-collection
# Set variables GL_TOKEN and GH_TOKEN when needed
# Put here commands from .gitlab-ci.yml job:before_script and job:script
# For example job test-full:
apk -U upgrade
apk add bats
bats tests
# Result is similar to:
# 1..1
# ok 1 dummy test

Credits and Acknowledgments

• Martin Bružina - Author

Copyright and Licensing

• MIT License
• Copyright © 2023 Martin Bružina

Changelog and News

• Changelog

Notes and References

Dependencies

• Ansible
  • GitHub - ansible-community/ansible-lint: Best practices checker for Ansible
• checkov
• GitHub - xebis/repository-template: Well-manageable and well-maintainable repository template. - contains GitLab CI/CD, set of useful scripts, pre-commit, semantic-release, and Visual Studio Code suggested extensions

Recommendations

• GitHub - KeyboardInterrupt/awesome-ansible: Awesome Ansible List
• Shields.io: Quality metadata badges for open source projects

Suggestions

• Visual Studio Code with Extensions for Visual Studio Code:
  • Ansible - includes potentially unwanted extensions Python (Ansible dependency) and Pylance (could be uninstalled)

Further Reading

List further reading links here, or delete the section.

• Wikipedia: README
• Make a README: Because no one can read your mind (yet)