blauwe_lucht.docker_webapps

Overview

This Ansible role helps to run multiple web applications using HTTPS on one Docker host. It can use self-signed certificates or certificates from Let's Encrypt.

The role sets up a reverse proxy using nginx that forwards requests to the configured web applications. Each web application can automatically obtain a Let's Encrypt certificate to enable HTTPS. These certificates will be renewed automatically through a certbot container. If you don’t use Let's Encrypt, it will create self-signed certificates for HTTPS instead.

Current Status

This role is still in the alpha stage. It’s meant for testing only, and no automated tests have been created yet.

Requirements

Ensure that Docker is already running on the server. You can set this up using the role geerlingguy.docker.

Role Variables

docker_webapps

This is where you configure the web applications. For example:

docker_webapps:
  - name: samtris
    docker_image: blauwelucht/samtris:v2.0
    port: 8080
    volumes:
      - /var/log:/var/log

name: The name for the Docker service and the subdomain for the reverse proxy.
docker_image: The Docker image to use for the web app. Use a specific tag since the role won't check for updates.
port: The port where the web application listens inside the container.
volumes: Optional settings to define volume paths.

docker_webapps_use_lets_encrypt

Set this to true only if the Docker host is accessible from the internet, as Let's Encrypt needs to verify the certificate request. If set to false, a self-signed certificate will be used.

docker_webapps_domain_name

The main domain name that includes all subdomains.

docker_webapps_email_address

docker_webapps_organization_name

docker_webapps_country_name

These details are used to request both self-signed and Let's Encrypt certificates.

docker_webapps_docker_compose_project

The name for your Docker Compose project. Change it only if there’s already a project with that name.

docker_webapps_reverse_proxy_container_name

The name for the reverse proxy container. Only change this if a container with the same name already exists.

docker_webapps_certbot_renew_container_name

The name for the certbot container that handles certificate renewals. Change this only if there’s already a container with that name.

docker_webapps_certbot_staging_param

Set this to "--staging" if you’re testing to avoid hitting Let's Encrypt rate limits.

Dependencies

There are no dependencies.

Example Playbook

- hosts: servers
  roles:
  - name: blauwe_lucht/docker_webapps
    vars:
      docker_webapps:
      - name: samtris
        docker_image: blauwelucht/samtris:v2.0
        port: 8080
      docker_webapps_use_lets_encrypt: true
      docker_webapps_domain_name: example.com
      docker_webapps_email_address: [email protected]
      docker_webapps_organization_name: ACME
      docker_webapps_country_name: NL

Notes

Make sure the Fully Qualified Domain Name (FQDN) like <site.domain> points to your server. This helps the reverse proxy direct requests to the correct web application.
nginx listens to an additional site name for testing: <site>-tst.<domain>.
Use image tags to update web application containers effectively. Change the tag in the docker_webapps settings to pull the new images.
To delete or refresh a Let's Encrypt certificate, run certbot delete --cert-name <fqdn> in the certbot container. Do this carefully as deleting/refreshing multiple certificates at once may cause issues with nginx.
Even without Let's Encrypt, web applications are accessible via HTTPS, but a browser warning will appear for self-signed certificates.