v0.2.0 - rename set_locale to locale_config, add test_connection.yml playbook and update READMEs

.gitignore

@@ -13,7 +13,6 @@ test.yml
 !.vscode/tasks.json
 !.vscode/launch.json
 !.vscode/extensions.json
-*.code-workspace
 
 # Local History for Visual Studio Code
 .history/

CHANGELOG.md

@@ -0,0 +1,14 @@
+# changelog
+
+## 0.2.0
+* [role] ⚠️ rename `set_locale` to `locale_config` along with the variable names (prefix)
+* [playbook] add `test_connection.yml` playbook which tests the connection to a target host including `become`
+* [docs] update [README](README.md) to reflect the latest changes
+* [docs] add READMEs for all roles
+* [dev] changes regarding the development environment:
+  * add setup script
+  * add pip requirements files
+  * add vscode workspace file
+
+## 0.1.4
+anything before 0.2.0 see [commit history](https://gitea.wululu.de/dede/ansible-common/commits/branch/main)

README.md

@@ -1,4 +1,11 @@
-# Ansible Collection - dede.common
+# Ansible Collection - `dede.common`
+```
+     _          _                                                 
+  __| | ___  __| | ___   ___ ___  _ __ ___  _ __ ___   ___  _ __  
+ / _` |/ _ \/ _` |/ _ \ / __/ _ \| '_ ` _ \| '_ ` _ \ / _ \| '_ \ 
+| (_| |  __/ (_| |  __/| (_| (_) | | | | | | | | | | | (_) | | | |
+ \__,_|\___|\__,_|\___(_)___\___/|_| |_| |_|_| |_| |_|\___/|_| |_|
+```
 
 this ansible collection primarily aims to provide common roles that i've been building
 for either my home or the wululu web network and systems.  
@@ -8,17 +15,25 @@ please mind that everything in this collection mainly focuses debian as a server
 thus i will not add features specific to other operating systems unless i really need to.  
 if you have any questions or suggestions feel free to get in touch with me.
 
-## roles
+## contents
 
-* **test** – a simple role to test ansible or just this collection  
-  it will run a debug task printing 'hello world'
-* **config_locale** – role to configure system locale and language settings  
-  you should set `system_locale` and `system_language` if you want to deviate from the default:  
-  ```
-  system_locale: 'de_DE.UTF-8'
-  system_language: 'en_US.UTF-8'
-  ```
-* **docker** – a docker install role that can install docker-ce engine in two ways:  
-  1. from the official docker repository (recommended by docker)
-  2. from your distribution
-  you can switch to the distribution method by setting `docker_use_dist_repo` to `true` (defaults to `false`).
+### roles
+* **test** – a simple test role which runs a `debug` task printing 'hello world'
+* **locale_config** – role to configure system locale and language settings [🠞README](roles/locale_config/README.md)
+* **docker** – a docker install role to install docker-ce engine [🠞README](roles/docker/README.md)
+
+### playbooks
+* **test_connection.yml** – a playbook to test ansible and connectivity by running the `test` and the role 
+
+## usage
+to use a **playbook** provided with this collection you can use `import_playbook`:
+```yaml
+- ansible.builtin.import_playbook: dede.common.test_connection.yml
+```
+
+to use a **role** provided with this collection just reference it using the collection name as a prefix:  
+```yaml
+- hosts: all
+  roles:
+    - dede.common.test
+```

ansible-common.code-workspace

@@ -0,0 +1,27 @@
+{
+	"folders": [
+	  {
+			"path": "."
+	  }
+	],
+	"settings": {
+	  "files.associations": {
+			"*.yml": "ansible",
+			"*.j2": "ansible-jinja"
+	  },
+	  "ansible.python.interpreterPath": "${workspaceFolder}/.venv/bin/python",
+	  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+	  "editor.tabSize": 2,
+	  "trailing-spaces.highlightCurrentLine": false,
+	  "trailing-spaces.schemeIgnore": [
+			"markdown",
+			"output"
+		]
+	},
+	"extensions": {
+	  "recommendations": [
+			"redhat.ansible",
+			"shardulm94.trailing-spaces"
+	  ]
+	}
+}

galaxy.yml

@@ -8,7 +8,7 @@ namespace: dede
 name: common
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 0.1.4
+version: 0.2.0
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md
@@ -46,7 +46,7 @@ dependencies: {}
 repository: https://gitea.wululu.de/dede/ansible-common
 
 # The URL to any online docs
-documentation: https://gitea.wululu.de/dede/ansible-common/wiki
+documentation: https://gitea.wululu.de/dede/ansible-common/src/branch/main/README.md
 
 # The URL to the homepage of the collection/project
 homepage: https://gitea.wululu.de/dede/ansible-common
@@ -66,4 +66,3 @@ build_ignore: []
 # 'omit_default_directives' is a boolean that controls whether the default directives are used. Mutually exclusive
 # with 'build_ignore'
 # manifest: null
-

requirements-freeze.txt

@@ -0,0 +1,30 @@
+ansible==11.1.0
+ansible-compat==24.10.0
+ansible-core==2.18.1
+ansible-lint==24.12.2
+attrs==24.3.0
+black==24.10.0
+bracex==2.5.post1
+cffi==1.17.1
+click==8.1.8
+cryptography==44.0.0
+filelock==3.16.1
+importlib_metadata==8.5.0
+Jinja2==3.1.5
+jsonschema==4.23.0
+jsonschema-specifications==2024.10.1
+MarkupSafe==3.0.2
+mypy-extensions==1.0.0
+packaging==24.2
+pathspec==0.12.1
+platformdirs==4.3.6
+pycparser==2.22
+PyYAML==6.0.2
+referencing==0.35.1
+resolvelib==1.0.1
+rpds-py==0.22.3
+ruamel.yaml==0.18.6
+subprocess-tee==0.4.2
+wcmatch==10.0
+yamllint==1.35.1
+zipp==3.21.0

requirements.txt

@@ -0,0 +1,2 @@
+ansible
+ansible-lint

roles/docker/README.md

@@ -1,5 +1,5 @@
-# docker role
+# dede.common.docker
 
-this role will simply install the docker engine (community edition) from the official docker repositories.
+this role will simply ensure the docker engine (community edition) is installed from the official docker repositories.
 
 source: https://docs.docker.com/engine/install/debian/#install-using-the-repository

roles/locale_config/README.md

@@ -0,0 +1,9 @@
+# dede.common.locale_config
+
+this role will ensure the system locale and language settings  
+you can modify `system_locale` and `system_language` if you want to deviate from the default, which is:
+
+```yaml
+locale_config_locale: 'de_DE.UTF-8'
+locale_config_language: 'en_US.UTF-8'
+```

roles/locale_config/defaults/main.yml

@@ -0,0 +1,3 @@
+---
+locale_config_locale: 'de_DE.UTF-8'
+locale_config_language: 'en_US.UTF-8'

roles/set_locale/defaults/main.yml

@@ -1,3 +0,0 @@
----
-set_locale_locale: 'de_DE.UTF-8'
-set_locale_language: 'en_US.UTF-8'

roles/test/README.md

@@ -0,0 +1,3 @@
+# dede.common.test
+
+a role that simply will print 'hello world!'

setup.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+
+# exit immediately if a command exits with a non-zero status
+set -e
+
+VENV_DIR=.venv
+
+# define color codes for output
+RED=$(tput setaf 1)
+GREEN=$(tput setaf 2)
+YELLOW=$(tput setaf 3)
+BLUE=$(tput setaf 4; tput bold)
+NC=$(tput sgr0) # no color
+
+# function to check for required commands
+check_command() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo -e "${RED}error: $1 is not installed. please install it and try again.${NC}" >&2;
+    exit 1;
+  }
+}
+
+# function to install the latest python
+install_python() {
+  echo -e "${BLUE}installing the latest python...${NC}"
+  sudo pacman -S python --noconfirm
+}
+
+# function to create a virtual environment
+create_virtualenv() {
+  check_command "python"
+  echo -e "${BLUE}creating virtual environment...${NC}"
+  if [ ! -d "$VENV_DIR" ]; then
+    python -m venv $VENV_DIR
+    echo -e "${GREEN}virtual environment created at $VENV_DIR${NC}"
+  else
+    echo -e "${YELLOW}virtual environment already exists at $VENV_DIR${NC}"
+  fi
+}
+
+# function to install python requirements
+install_requirements() {
+  check_command "pip"
+  echo -e "${BLUE}installing python requirements from requirements-freeze.txt...${NC}"
+  source $VENV_DIR/bin/activate
+  pip install --upgrade pip
+  if [ -f "requirements-freeze.txt" ]; then
+    pip install -r requirements-freeze.txt
+  else
+    echo -e "${YELLOW}requirements-freeze.txt not found. skipping python requirements installation.${NC}"
+  fi
+  deactivate
+}
+
+# function to install ansible roles from requirements.yml
+install_ansible_requirements() {
+  check_command "ansible-galaxy"
+  echo -e "${BLUE}installing ansible roles from requirements.yml...${NC}"
+  if [ -f "requirements.yml" ]; then
+    source $VENV_DIR/bin/activate
+    ansible-galaxy install -r requirements.yml
+    deactivate
+  else
+    echo -e "${YELLOW}requirements.yml not found. skipping ansible requirements installation.${NC}"
+  fi
+}
+
+# main script execution
+install_python                # install the latest python
+create_virtualenv             # create a virtual environment
+install_requirements          # install python requirements
+install_ansible_requirements  # install ansible requirements
+
+echo -e "${GREEN}setup completed successfully!${NC}"

test_connection.yml

@@ -0,0 +1,14 @@
+---
+- name: test play
+  hosts: "{{ target | default([]) }}"
+  tasks:
+    - name: say hello to the world
+      ansible.builtin.debug:
+        msg: hello world!
+
+    - name: check connection using ping
+      ansible.builtin.ping:
+
+    - name: check become using ping
+      become: true
+      ansible.builtin.ping: