Ansible Nginx Role with Multi-Distro Molecule Testing

A production-ready Ansible role for deploying Nginx across multiple Linux distributions (Alpine, Ubuntu, CentOS) with a comprehensive Molecule test suite.

Features

• Multi-Distro Support: Tested and working on Alpine Linux, Ubuntu, and CentOS/RHEL
• Dynamic Content: Custom Jinja2 template displaying system information
• Complete Testing: Molecule with Testinfra for validation across platforms
• Production-Ready: Uses FQCN (Fully Qualified Collection Names) for Ansible tasks

Project Structure

.
├── requirements.txt
├── roles/
│   └── nginx/
│       ├── defaults/
│       │   └── main.yml
│       ├── handlers/
│       │   └── main.yml
│       ├── tasks/
│       │   └── main.yml
│       └── templates/
│           └── index.html.j2
└── molecule/
    └── default/
        ├── converge.yml
        ├── molecule.yml
        └── verify.py

Prerequisites

• Python 3.8+
• Docker
• Virtual environment (recommended)

Quick Start

1. Create and activate virtual environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

2. Install dependencies

pip install -r requirements.txt

3. Install Ansible collections

# Install community.general collection (required for openrc module)
collection install community.general

4. Run the test suite

# Run full molecule test suite
molecule test

# Or run individual stages
molecule create      # Start Docker containers
molecule converge    # Apply Ansible role
molecule verify      # Run Testinfra tests
molecule destroy     # Cleanup containers

Configuration

Default Variables

Edit roles/nginx/defaults/main.yml to customize:

# Nginx default variables
nginx_package: nginx
nginx_service: nginx
nginx_conf_dir: "/etc/nginx"
nginx_doc_root: "/usr/share/nginx/html"
nginx_listen_port: 80
nginx_server_name: "localhost"
nginx_worker_processes: auto

Custom Playbook

To use the role in your own playbook:

---
- name: Deploy Nginx
  hosts: all
  become: yes

  roles:
    - role: nginx
      nginx_listen_port: 80
      nginx_server_name: "example.com"

Testing Platform Details

Molecule Tests

The test suite validates the following on each platform:

1. Alpine Linux (alpine:latest)

   • Uses OpenRC init system
   • Package manager: apk

2. Ubuntu (ubuntu:latest)

   • Uses systemd init system
   • Package manager: apt

3. CentOS 7 (geerlingguy/docker-centos7-ansible:latest)

   • Uses systemd init system
   • Package manager: yum

Test Assertions (verify.py)

The Testinfra suite verifies:

• ✅ Nginx package is installed
• ✅ Nginx service is running
• ✅ Port 80 is listening
• ✅ HTTP response contains "Hello World"

Supported Operating Systems

OS	Version	Init System	Package Manager
Alpine Linux	latest	OpenRC	apk
Ubuntu	20.04/22.04/24.04	systemd	apt
CentOS	7	systemd	yum
RHEL/Rocky	8/9	systemd	dnf

Custom Index Page

The role deploys a custom index.html.j2 template that displays:

• Current Date and Time
• Operating System Information
• Nginx Version
• System Details (Memory, CPU, Kernel)
• Network Information

Access the page at http://localhost/ after deployment.

Troubleshooting

Common Issues

1. Containers fail to start

   # Check Docker status
   docker ps -a
   
   # Ensure you have Docker permissions
   sudo usermod -aG docker $USER

2. Testinfra tests fail

   # Run with verbose output
   molecule verify -- -v
   
   # Check converge logs first
   molecule converge -v

3. Ansible errors

   # Run playbook with verbose mode
   ansible-playbook molecule/default/converge.yml -vvv

4. Permission denied when starting services

   • Ensure containers are running with privileged: true in molecule.yml
   • Check Docker daemon is running

Development

Adding New Tests

Edit molecule/default/verify.py to add new assertions:

def test_nginx_custom_content(host):
    output = host.check_output("curl -s http://localhost/")
    assert "Your custom string" in output

Adding New Platforms

Edit molecule/default/molecule.yml and add new platform:

- name: instance-debian
  image: debian:bookworm
  pre_build_image: true
  privileged: true

License

MIT License - See LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Run molecule test to ensure all tests pass
4. Submit a pull request

Author

Created for production deployment of Nginx with comprehensive test coverage.