maxmind

Overview

This role allows you to install geoip and the maxmind database.

You need a maxmind account. To create one, follow these links:

• https://dev.maxmind.com/geoip/updating-databases
• https://www.wpdiaries.com/country-by-ip/

Requirements

This role works on Ubuntu.

Role Variables

You need to set your maxmind account details:

maxmind_account_id: __YOUR_ACCOUNT_ID__
maxmind_license_key: __YOUR_LICENSE_KEY__
maxmind_edition_ids: GeoLite2-ASN GeoLite2-City GeoLite2-Country
maxmind_geoipupdate_run: true  # run geoipupdate during installation
maxmind_geoipupdate_cron: true  # create a job to regularly run geoipupdate

Example Playbook

- hosts: maxmind
  roles:
    - { role: andrelohmann.maxmind }

Role Development

Purpose

This repository supports the following for role development:

• yamllint
• ansible-lint
• molecule testing
• GitHub actions
• automatic version updates
• ansible-galaxy updates
• build status display
• testing with Vagrant (for development)
• testing with Molecule (inside or outside Vagrant)
• Docker container testing
• developing within VS Code

Prerequisites

For detailed information, visit: https://thedatabaseme.de/2022/01/17/automated-testing-your-ansible-role-with-molecule-and-github-actions/

• Install VirtualBox + Vagrant (needed only if testing with Vagrant)
• Docker Desktop
• Visual Studio Code + remote extension pack (dependencies are listed in .vscode/extensions.json)

Development Setup

This ansible role uses Molecule for testing. Development is done in Visual Studio Code with a container that has all necessary tools (Ansible, linter, Molecule).

Testing will be performed on Ubuntu Jammy.

To start Molecule test containers from the development container, the Docker socket must be bind mounted.

Important Folders and Files

.devcontainer

• Contains the Dockerfile for the development container.
• Configures how the development container starts (e.g., bind mount for Docker socket).

molecule/default/Dockerfile.js

• Template for all platforms defined in molecule/default/molecule.yml.
• Prepares environments to support systemd services (needed for some Ansible roles).
• Installs all requirements for running Ansible against the derived container.
• Aligns with the platforms defined in molecule/default/molecule.yml.
• For more details, refer to the Molecule documentation.

Usage

Visual Studio Code

• Go to the root directory of your role and start VS Code:

code .

• Within the development container, you can run the following commands:

yamllint .
ansible-lint .
molecule create
molecule test

Vagrant + Virtualbox

• Go to the root directory of your role.
• Go to the vagrant folder.
• Start and enter the Vagrant machine:

vagrant up
vagrant ssh

• Navigate to the role folder:

cd /etc/ansible/roles/ansible-role- [tab]

• Now you can run all tests:

yamllint .
ansible-lint .
molecule create
molecule test

Build and Release Process

The Ansible role defines several GitHub workflows for testing and managing releases.

Protect the master/main branch

• Go to Settings -> Branches -> Add branch protection rule.
• Set Branch pattern name -> main or master (depending on your branch).
• Check "Require a pull request before merging".
• Set "Require approvals" as needed.

Grant read and write permissions to GITHUB_TOKEN

• Go to Settings -> Actions -> General -> Workflow permissions -> select read and write permissions.

Commit Messages

Follow a format for commit messages to achieve patch, minor, or major updates.

Patch

0.0.x

fix(single_word): description

Minor

0.x.0

feat(single_word): description

Major

x.0.0

perf(single_word): description
BREAKING CHANGE: explaining the breaking change

Make sure to mention "BREAKING CHANGE: " in the second line. If the commit message is a single line, the major version update will be ignored.

Add GALAXY_API_KEY secret

• Log in to your GitHub account at https://galaxy.ansible.com/.
• Get your galaxy API key from Preferences -> API Key.
• Open your GitHub role repository.
• Go to Settings -> Secrets and variables -> Actions -> New repository secret.
• Use "GALAXY_API_KEY" as the key and your copied API key as the value.

License

MIT

Author Information

© Andre Lohmann (and others) 2024

https://github.com/andrelohmann

Maintainer Contact

• Andre Lohmann <lohmann.andre (at) gmail (dot) com>