jonaspammer.core_dependencies

// This file is generated by .github/workflows/gh-pages.yml - local changes will be lost!
= ansible-role-core_dependencies
Jonas Pammer <[email protected]>;
:toc: left
:toclevels: 2
:toc-placement!:
:source-highlighter: rouge

https://galaxy.ansible.com/jonaspammer/core_dependencies[Available on Ansible Galaxy: Version Badge]
// Status Badges
https://github.com/JonasPammer/ansible-role-core_dependencies/actions/workflows/ci.yml[Testing CI Badge]

This Ansible role installs essential system packages needed for various Ansible core modules, including:

* `ansible.builtin.apt_repository`
* `ansible.builtin.archive`
* `ansible.builtin.debconf`
* `ansible.builtin.dnf`
* `ansible.builtin.git`
* `ansible.builtin.subversion`
* `ansible.builtin.unarchive`
* `ansible.builtin.user`
* `ansible.builtin.yum`
* `ansible.posix.seboolean`

This role also maintains an updated package cache for most systems.

Typically, you will use this role alongside my 
https://github.com/JonasPammer/ansible-role-bootstrap[`bootstrap role`].


[NOTE]
.DISCLAIMER
=====
This role is a modified version of 
https://github.com/robertdebock/ansible-role-core_dependencies/releases/tag/2.1.9[robertdebock's core_dependencies role] (v2.1.9) as of February 11, 2022,
with added code comments only.
=====

toc::[]

[[meta]]
== 🔎 Metadata
Here you can find details about:

* Required Ansible version for the role
* Supported platforms 
* Role dependencies 

.link:meta/main.yml[]
[source,yaml]
----
---
galaxy_info:
  role_name: "core_dependencies"
  description:
    "An ansible role for installing dependencies for the Ansible core modules.
    Based on robertdebock's core_dependencies role."

  author: "jonaspammer"
  license: "MIT"

  min_ansible_version: "2.11"
  platforms:
    - name: EL # (Enterprise Linux)
      versions:
        - "9" # tested: rockylinux9
    - name: Fedora
      versions:
        - "38" # tested: fedora38
        - "39" # tested: fedora39
    - name: Debian
      versions:
        - bullseye # tested: debian11
        - bookworm # tested: debian12
    - name: Ubuntu
      versions:
        - focal # tested: ubuntu2004
        - jammy # tested: ubuntu2204

  galaxy_tags: []

dependencies: []
----

[[requirements]]
== 📌 Requirements
// Any prerequisites not covered by the role or Ansible should be mentioned here.
The Ansible User must have the ability to `become`.

The https://galaxy.ansible.com/community/general[`community.general` collection]
must be installed on the Ansible controller.


[[variables]]
== 📜 Role Variables
// Describe the variables for this role here. Mention any variables read from other roles or the global scope.

[[public_vars]]
== 📜 Facts/Variables defined by this role

Variables in this section are defined during role execution (can only be overwritten using `ansible.builtin.set_facts`) 
and are also used externally.

[[tags]]
== 🏷️ Tags

Tasks are tagged with:
[cols="1,1"]
|===
|Tag | Purpose

2+| This role has no officially documented tags yet.
// | download-xyz
// | install-prerequisites
// | install
// | create-xyz
|===

Use Ansible to skip or only run tasks designated by these tags. By default, all tasks run if no tags are specified.

[[dependencies]]
== 👫 Dependencies
// List other roles here, plus any parameter details needed for them.

[[example_playbooks]]
== 📚 Example Playbook Usages
// Include examples of how to use this role in common scenarios.

[NOTE]
====
This role is part of 
https://github.com/JonasPammer/ansible-roles[
many specific-purpose roles of mine].

Prepare the machine.
In CI, this is done in `molecule/resources/prepare.yml`
which sources soft dependencies from `requirements.yml`:

.link:molecule/resources/prepare.yml[]
[source,yaml]
----
---
- name: prepare
  hosts: all
  become: true
  gather_facts: false

  roles:
    - role: jonaspammer.bootstrap
----

The diagram below shows the dependencies of this role along with their recursive dependencies.

image:https://raw.githubusercontent.com/JonasPammer/ansible-roles/master/graphs/dependencies_core_dependencies.svg[
requirements.yml dependency graph of jonaspammer.core_dependencies]
====

.Minimum Viable Play
====
[source,yaml]
-----
---
- hosts: servers:&provisioned
  name: Bootstrap Linux machines for Ansible management.
  gather_facts: false

  roles:
    - role: jonaspammer.core_dependencies
-----
====

.More Common Play
====
[source,yaml]
-----
---
- hosts: servers:&provisioned
  name: Bootstrap Linux machines for Ansible management.
  become: false
  gather_facts: false

  roles:
    - role: jonaspammer.bootstrap
    - role: jonaspammer.core_dependencies
      become: "{{ bootstrap_become | default(omit) }}"
      become_user: "{{ bootstrap_become_user | default(omit) }}"
-----
====


[[tested-distributions]]
== 🧪 Tested Distributions

This role may work on various distributions, like Red Hat Enterprise Linux (RHEL),
even if there are no specific tests for that distribution.
// Reference: geerlingguy's most starred project:
// https://github.com/geerlingguy/ansible-role-docker/blob/master/.github/workflows/ci.yml
|===
| OS Family | Distribution | Release Date | End of Life | Docker Image

// https://endoflife.date/rocky-linux
| Rocky
| Rocky Linux 8 (similar to RHEL/CentOS 8)
| 2021-06
| 2029-05
| https://github.com/geerlingguy/docker-rockylinux8-ansible/actions?query=workflow%3ABuild[CI]

| Rocky
| Rocky Linux 9
| 2022-07
| 2032-05
| https://github.com/geerlingguy/docker-rockylinux9-ansible/actions?query=workflow%3ABuild[CI]

// https://endoflife.date/fedora (13 Months)
| RedHat
| Fedora 39
| 2023-11
| 2024-12
| https://github.com/geerlingguy/docker-fedora39-ansible/actions?query=workflow%3ABuild[CI]

// https://ubuntu.com/about/release-cycle
| Debian
| Ubuntu 20.04 LTS
| 2021-04
| 2025-04
| https://github.com/geerlingguy/docker-ubuntu2004-ansible/actions?query=workflow%3ABuild[CI]

| Debian
| Ubuntu 22.04 LTS
| 2022-04
| 2027-04
| https://github.com/geerlingguy/docker-ubuntu2204-ansible/actions?query=workflow%3ABuild[CI]

// https://wiki.debian.org/DebianReleases
| Debian
| Debian 11
| 2021-08
| 2024-06 (LTS)
| https://github.com/geerlingguy/docker-debian11-ansible/actions?query=workflow%3ABuild[CI]

| Debian
| Debian 12
| 2023-06
| 2026-06 (LTS)
| https://github.com/geerlingguy/docker-debian12-ansible/actions?query=workflow%3ABuild[CI]
|===


[[tested-ansible-versions]]
== 🧪 Tested Ansible Versions

Tested Ansible versions align with the
https://github.com/ansible-collections/community.general#tested-with-ansible[
support pattern of the `community.general` collection].
As of now:

* 2.13 (Ansible 6)
* 2.14 (Ansible 7)
* 2.15 (Ansible 8)
* 2.16 (Ansible 9)


[[development]]
== 📝 Development
// Badges for Project Conventions
https://conventionalcommits.org[Conventional Commits Badge]
https://results.pre-commit.ci/latest/github/JonasPammer/ansible-role-core_dependencies/master[pre-commit.ci status]
// image:https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white[pre-commit, link=https://github.com/pre-commit/pre-commit]

[[development-system-dependencies]]
=== 📌 Development Machine Dependencies

* Python 3.10 or greater
* Docker

[[development-dependencies]]
=== 📌 Development Dependencies
Development Dependencies are specified in a
https://pip.pypa.io/en/stable/user_guide/#requirements-files[pip requirements file]
named `requirements-dev.txt`.
Example Installation Instructions for Linux are shown below:

----
# Optional: create a Python virtual environment and activate it
$ python3 -m venv venv
$ source venv/bin/activate

$ python3 -m pip install -r requirements-dev.txt
----

[[development-guidelines]]
=== ℹ️ Ansible Role Development Guidelines

Check out my 
https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_GUIDELINES.adoc[
Ansible Role Development Guidelines].

If interested, I've also shared some 
https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_TIPS.adoc[
General Ansible Role Development Tips].

[[versioning]]
=== 🔢 Versioning

Versions are defined using 
https://git-scm.com/book/en/v2/Git-Basics-Tagging[Tags],
which are recognized by Ansible Galaxy.

*Versions should not start with `v`.*

When a new tag is pushed, 
https://github.com/JonasPammer/ansible-role-core_dependencies/actions/workflows/release-to-galaxy.yml[
a GitHub CI workflow] will import the role to my Ansible Galaxy Account.

[[testing]]
=== 🧪 Testing
Automatic tests run on each contribution using GitHub Workflows.

The tests mainly involve running 
https://molecule.readthedocs.io/en/latest/[Molecule]
across <<tested-distributions,varying Linux distributions>>
and <<tested-ansible-versions,several Ansible versions>>.

The Molecule test includes steps that lint all Ansible playbooks with 
https://github.com/ansible/ansible-lint#readme[`ansible-lint`] 
to ensure best practices.

To run the tests, execute `tox` in the command line:

$ tox

You can also set an optional environment variable to specify the Docker container distribution:

$ MOLECULE_DISTRO=ubuntu2204 tox

For potential `MOLECULE_DISTRO` values, check the matrix defined in link:.github/workflows/ci.yml[].

==== 🐛 Debugging a Molecule Container

1. Run your Molecule tests with `MOLECULE_DESTROY=never`, e.g.:

$ MOLECULE_DESTROY=never MOLECULE_DISTRO=ubuntu1604 tox -e py3-ansible-5 ...

2. Find the name of the Molecule-provisioned Docker container:

$ docker ps #30e9b8d59cdf# geerlingguy/docker-debian12-ansible:latest "/lib/systemd/systemd" 8 minutes ago Up 8 minutes instance-py3-ansible-9

3. Access the Docker container’s shell for debugging:

$ docker exec -it #30e9b8d59cdf# /bin/bash

[TIP]
====
If your issue happens during the `verify.yml` step, you may want to know that Ansible's variables (`vars`), hosts (`hostvars`), and environment variables are stored in:
* `/var/tmp/vars.yml` (with host variables)
* `/var/tmp/environment.yml`
You can use `grep`, `cat`, or transfer these files as needed.
====

4. When done debugging, exit and destroy the container:

root@instance-py3-ansible-2:/# exit $ docker stop #30e9b8d59cdf# $ docker container rm #30e9b8d59cdf# or $ docker container prune

==== 🐛 Debugging Local Package Versions

By default, `tox` 3 recognizes CI variables, enabling:

$ CI=true tox

[[development-container-extra]]
=== 🧃 TIP: Containerized Development Environment

This project includes a "1-Click Containerized Development Environment."

This container allows running Docker containers within it (Docker-In-Docker), enabling molecule execution.

To use it:

1. Ensure you meet the link:https://code.visualstudio.com/docs/remote/containers#_system-requirements[System requirements for Visual Studio Code Development Containers].
2. Clone the project to your machine.
3. Open the repo folder in Visual Studio Code (_File - Open Folder…_).
4. If prompted, you can enter the devcontainer definition; otherwise, execute `Remote-Containers: Open Folder in Container `. 

[TIP]
====
Consider using `Remote-Containers: Rebuild Without Cache and Reopen in Container` to ensure changes are recognized properly.
====

[NOTE]
=====
You may need to configure your host system for the container to access your SSH/GPG keys.
Refer to the official docs on "Sharing Git credentials with your container" for guidance.
=====


[[cookiecutter]]
=== 🍪 CookieCutter

This project is kept synced with 
https://github.com/JonasPammer/cookiecutter-ansible-role[the original CookieCutter template]
using 
https://github.com/cruft/cruft[cruft] or manual changes as needed.

.Usage Example for `cruft update`
____
image::https://raw.githubusercontent.com/cruft/cruft/master/art/example_update.gif[Usage Example for `cruft update`]
____

==== 🕗 Changelog
When a new tag is pushed, a GitHub Release will be created for a human-readable changelog.

[[pre-commit]]
=== ℹ️ Linting and Styling Conventions
Linting and styling are enforced using various 
https://pre-commit.com/[`pre-commit`] hooks.

Automatic execution of pre-commit checks is done on each contribution with 
https://pre-commit.ci[`pre-commit.ci`].
Pull requests get automatically fixed by these hooks as well.

[NOTE]
====
To avoid confusion:
While some hooks can warn you about syntax issues, 
they do not run real test suites. For more on testing, see <<testing>>.
====

[TIP]
====
[[note_pre-commit-ci]]
I recommend integrating pre-commit into your local development workflow.
To do this, go into your project directory and run `pre-commit install`. This makes Git run pre-commit checks on every commit, stopping commits if any hook fails.

You can also execute pre-commit hooks at any time with `pre-commit run --all-files`.
====

[[contributing]]
== 💪 Contributing
https://open.vscode.dev/JonasPammer/ansible-role-core_dependencies[Open in Visual Studio Code]
image:https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square[PRs Welcome]

// Included in README.adoc
:toc:
:toclevels: 3

The sections below offer guidance for new contributors.
Actual "Development Documentation" is found under <<development>>.

=== 🤝 Preamble
Thank you for considering contributing to this project.

Following these guidelines shows respect for developers' time managing this open-source project, and they should reciprocate by addressing your issue and assisting with your pull requests.

[[cookiecutter--contributing]]
=== 🍪 CookieCutter
This project owes many files to 
https://github.com/JonasPammer/cookiecutter-ansible-role[the original CookieCutter template].

Check if your intended edits are more suited for the template, and make appropriate changes there if so. Your change may apply partly to the template and partly to this project, in which case you would have to create multiple PRs.

=== 💬 Conventional Commits

Casual contributors need not worry about adhering to 
https://www.conventionalcommits.org/en/v1.0.0/[the spec], 
as PRs are merged into one commit during the process. Only core contributors must follow it for automatic version and changelog generation.

=== 🚀 Getting Started

Contribute via Issues and Pull Requests (PRs). General guidelines:
* Search for existing Issues and PRs before creating new ones.
* For first-time contributors, refer to the 
https://auth0.com/blog/a-first-timers-guide-to-an-open-source-project/[first timer's guide on Auth0's blog] for helpful resources.

==== Issues

Use Issues for reporting problems, making feature requests, or discussing changes *before* creating a PR.
Upon creating a new issue on 
https://github.com/JonasPammer/ansible-role-core_dependencies/issues/new[GitHub], a template will guide you in providing relevant information.

If there's an existing Issue covering your problem, add your reproduction info there 
instead of creating a new one.
Adding a 
https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/[reaction]
can also signal to maintainers that a problem affects others too.

==== Pull Requests

PRs are always welcome and can be a quick way to get your fix or improvement made.
In general, PRs should:
* Only fix/add functionality for one concern *OR* modify whitespace/style issues.
* Add unit or integration tests for any modified functionality (if a test suite exists).
* Address a single concern.
* Include documentation in the repo.
* Follow the complete Pull Request template for efficient review.

For significant changes or breaking changes (major releases), discuss your proposal first via an Issue.

Adhere to the "fork-and-pull" Git workflow:
1. Fork the repository to your GitHub account.
2. Clone the project locally.
3. Create a descriptive branch locally.
4. Commit your changes.
5. Follow any repo-specific formatting and testing guidelines.
6. Push changes to your fork.
7. Open a PR in our repository and follow the PR template for a smooth review.

[[changelog]]
== 🗒 Changelog
Check the 
https://github.com/JonasPammer/ansible-role-core_dependencies/releases[Release Page]
for a human-readable changelog related to tags (versions) in this project.

This project follows Semantic Versioning. Report any accidental breaking changes from minor version updates.

[[license]]
== ⚖️ License

.link:LICENSE[]
----
MIT License

Copyright (c) 2022, Jonas Pammer

Permission is granted, free of charge, to anyone obtaining a copy of this software to use, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, under the following conditions:

The copyright notice and permission must be included in all copies or significant portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, including but not limited to warranties of merchantability and fitness for a particular purpose. The authors are not liable for any claim, damages, or other liabilities arising from the use of the software.

----