ansible-collection-webserver/README.md

# Ansible Collection - s3lph.webserver

Configure Apache2 and Certbot, with an auto-bootstrap mechanism.

## Usage Examples

### Multi-VHost Setup with Let's Encrypt Certificates

We start with the following playbook:

```yaml
- hosts: webserver
  roles:
    - s3lph.webserver.apache2
    - s3lph.webserver.certbot
```

To configure our VHosts, we create a hostvars file, e.g. `host_vas/web01.example.org/apache2.yml`:

```yaml
apache2_sites:

  # This simply serves /var/www/foo.example.org/html under the vhost foo.example.org.
  foo.example.org:
    documentroot: /var/www/foo.example.org/html
    tls_certfile: /etc/letsencrypt/live/foo.example.org/fullchain.pem
    tls_keyfile: /etc/letsencrypt/live/foo.example.org/privkey.pem

  # A simple reverse-proxy example
  bar.example.org:
    aliases:
	  - baz.example.org
    documentroot: /var/www/bar.example.org/html
    tls_certfile: /etc/letsencrypt/live/bar.example.org/fullchain.pem
    tls_keyfile: /etc/letsencrypt/live/bar.example.org/privkey.pem
	# You can add any Apache2 config to the VHost config
	additional_config: |
      ProxyPass / http://localhost:8080/
      ProxyPassReverse / http://localhost:8080/
```

To tell the certbot role which certificates to issue, create another hostvars file such as `host_vas/web01.example.org/certbot.yml`:

```yaml
certbot_certificates:
  foo.example.org:
    webroot_map:
	  foo.example.org: /var/www/foo.example.org/html
  bar.example.org:
    webroot_map:
	  bar.example.org: /var/www/bar.example.org/html
	  baz.example.org: /var/www/bar.example.org/html
```

### Bootstrap

The bootstrap mechanism works in two steps:

- When the configured certificate files do not exist yet, the apache2 role instead uses Debian's default "snakeoil" certificate, resulting in a valid configuration, but using self-signed certificates.
- After the ACME challenge has been completed - which can be done with invalid certs - and the Apache2 role is applied a second time, it now configures the certificates issued by Let's Encrypt.

This can either be achieved by running the playbook from the previous example twice, or by invoking the Apache2 role twice in the same playbook (but in a second play):

```yaml
- hosts: webserver
  roles:
    - s3lph.webserver.apache2
    - s3lph.webserver.certbot

- hosts: webserver
  roles:
    - s3lph.webserver.apache2
```