webserver Role

This role installs and configures a web server stack based on Apache or Nginx, including PHP support and optional Let’s Encrypt SSL certificates.

Description

The webserver role provides a flexible and production‑ready setup for web servers.
It supports Apache and Nginx, installs PHP with configurable extensions, manages virtual hosts, and can optionally obtain and manage Let’s Encrypt certificates.

PHP runtime settings (php.ini) and PHP‑FPM pool settings (www.conf) are configurable in a declarative and upgrade‑safe way using override files and loops.

The role is designed to be idempotent, lint‑clean, and suitable for use inside an Ansible Collection.

Installation

1. Ensure that Ansible is installed on your system. The recommended version is at least 2.17.
2. Install the collection that contains this role using ansible-galaxy.
3. Ensure the following dependencies are available:
   • Apache or Nginx
   • PHP from distribution repositories or Sury packages (Debian/Ubuntu)
   • Certbot (optional, for Let’s Encrypt)

Variables

The role uses the following variables:

Web Server

• webserver_type: Web server to install.
  Supported values: apache, nginx.

• webserver_server_name: Primary server name (FQDN).
  Example: example.com.

• webserver_server_aliases: List of additional server names.
  Example: ["www.example.com"].

• webserver_server_root_subpath: Extends the document root of the virtual host.
  The final document root is assembled as:
  /var/www/ + webserver_server_name + webserver_server_root_subpath

  Example: /var/www/example.com/.

• webserver_template: Custom webserver vhost template filename. If not specified, defaults to nginx_vhost.conf.j2 for Nginx or apache_vhost.conf.j2 for Apache. Specify the template filename relative to the playbook directory.

PHP Installation

• webserver_php_version: PHP version to install.
  Example: 8.5.

• webserver_php_extensions: List of PHP extensions to install.
  Example: ["mysql", "gd", "curl"].

PHP Runtime Configuration (php.ini)

• webserver_php_ini_settings:
  List of PHP configuration overrides applied via
  /etc/php/<version>/fpm/conf.d/99-ansible.ini.

  Default: empty list ([])
  → No PHP settings are changed unless explicitly defined.

  Example:

  webserver_php_ini_settings:
    - section: PHP
      option: memory_limit
      value: 128M
    - section: PHP
      option: max_execution_time
      value: 30
  

PHP‑FPM Pool Configuration (www.conf)

• webserver_php_fpm_pool_settings:
  List of PHP‑FPM pool directives applied directly to
  /etc/php/<version>/fpm/pool.d/www.conf.

  Default: empty list ([])
  → No pool settings are modified unless explicitly defined.

  Example:

  webserver_php_fpm_pool_settings:
    - section: www
      option: pm
      value: dynamic
    - section: www
      option: pm.max_children
      value: 20
    - section: www
      option: pm.start_servers
      value: 4
    - section: www
      option: pm.min_spare_servers
      value: 2
    - section: www
      option: pm.max_spare_servers
      value: 6
  

SSL / Let’s Encrypt

• webserver_ssl_mode: SSL configuration mode.
  Supported values:

  • none
  • letsencrypt
  • custom

• webserver_letsencrypt_email: Email address for Let’s Encrypt registration.

Output Behavior

• Web server packages are installed and enabled.
• PHP and required extensions are installed.
• PHP runtime settings are applied via override files (no core files modified).
• PHP‑FPM pool settings are applied only when explicitly defined.
• Virtual hosts are created using a single template.
• SSL configuration is only applied after certificates exist.
• Configuration validity is tested (apachectl configtest / nginx -t) before reload.
• PHP‑FPM is reloaded automatically when configuration changes.

Usage

Example Playbook

- hosts: web
  tasks:
    - name: Start webserver role
      ansible.builtin.include_role:
        name: webserver
      vars:
        webserver_type: apache
        webserver_server_name: example.com
        webserver_php_version: "8.2"
        webserver_ssl_mode: letsencrypt
        webserver_php_ini_settings:
          - section: PHP
            option: memory_limit
            value: 128M
        webserver_php_fpm_pool_settings:
          - section: www
            option: pm.max_children
            value: 20

Features

• Apache and Nginx Support
• Single‑Template VHost Design
• Config Validation Before Reload
• Automatic Let’s Encrypt Integration
• PHP Version and Extension Management
• Upgrade‑Safe PHP Configuration Overrides
• PHP‑FPM Pool Tuning
• Handler‑Based Reload Logic
• Neutral Defaults (no hidden changes)

Contributing

Contributions are welcome!

1. Fork the repository.
2. Create a feature branch.
3. Submit a pull request with a clear description.

License

This project is licensed under the AGPL License.
Any modifications must be made available when distributed or provided over a network.