wkhtmltopdf

Overview

This role installs the wkhtmltopdf tool, which converts HTML to PDF, along with a full set of Google Fonts for use in the PDFs.

wkhtmltopdf is installed from the Ubuntu software sources.

Requirements

You need to use Ubuntu for this role.

Role Variables

You can set the following variable to choose whether to install all Google Fonts:

wkhtmltopdf_install_google_fonts: true

Find the latest version tag here.

Example Playbook

Here’s a simple playbook example:

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

Role Development

Features

This repository includes tools for developing the role, such as:

• yamllint
• ansible-lint
• molecule testing
• GitHub Actions
• Automatic version upgrade
• Update Ansible Galaxy
• Show build status
• Test with Vagrant (for development)
• Test with Molecule (inside or outside Vagrant)
• Test using Docker containers
• Develop in VSCode

Prerequisites

Ensure you have the following:

• VirtualBox + Vagrant (only if you plan to test with Vagrant)
• Docker Desktop
• Visual Studio Code + Remote Extension Pack (dependencies are in .vscode/extensions.json)

Development Setup

This Ansible role uses Molecule for testing and is developed in Visual Studio Code within a setup that manages all dependencies (like Ansible, linters, and Molecule).

The role will be tested on Ubuntu Jammy.

For testing Molecule containers, you need to mount the Docker socket in your development container.

Important Folders and Files

.devcontainer

• Defines the Dockerfile for the development container.
• Configures how to start the development container (e.g., mounting the Docker socket).

molecule/default/Dockerfile.js

• Template for all platforms listed in molecule/default/molecule.yml.
• Prepares environments to handle systemd services (important for some Ansible roles).
• Installs requirements to run Ansible inside the derived container.
• Aligns with the platform attributes in molecule/default/molecule.yml.
• For more details, refer to the Molecule documentation.

Usage

Visual Studio Code

• Open the root directory of your role and start VSCode:

code .

• Use the following commands inside your development container:

yamllint .
ansible-lint .
molecule create
molecule test

Vagrant + VirtualBox

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

vagrant up
vagrant ssh

• Change 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 includes GitHub workflows for testing and managing releases, which require some settings.

Protecting the Main Branch

• Go to Settings -> Branches -> Add branch protection rule.
• Enter the branch name (main or master, based on your default branch).
• Enable "Require a pull request before merging".
• You can set "Require approvals" as needed.

Grant Permissions to GITHUB_TOKEN

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

Commit Messages

Use specific formats for commit messages to manage versioning:

Patch Version

For version 0.0.x:

fix(single_word): description

Minor Version

For version 0.x.0:

feat(single_word): description

Major Version

For version x.0.0:

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

Make sure to include "BREAKING CHANGE:" on the second line or later, as it won't be recognized on a single-line commit.

Add GALAXY_API_KEY Secret

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

License

MIT

Author Information

© Andre Lohmann (and others) 2024

GitHub Repository

Maintainer Contact

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