Optimized instructions and default values for wildcard certificates

group_vars/all/00_general.yml

@@ -32,4 +32,13 @@ size_percent_disc_space_warning:  90  # Warning threshold in percent for free di
 # Runtime Variables for Process Control
 activate_all_timers:                  false   # Activates all timers, independend if the handlers had been triggered
 nginx_matomo_tracking:                false   # Activates matomo tracking on all html pages
-enable_one_letsencrypt_cert_for_all:  true    # Activates one letsencrypt cert for all instead of one per subdomain
+
+# One Wildcard Certificate for All Subdomains
+# Enables a single Let's Encrypt wildcard certificate for all subdomains instead of individual certificates.
+# Default: false (recommended for automatic setup).
+# Setting this to true requires additional manual configuration.
+# Using a wildcard certificate can improve performance by reducing TLS handshakes.
+# To enable, update your inventory file.
+# For detailed setup instructions, visit: 
+# https://github.com/kevinveenbirkenbach/cymais/tree/master/roles/nginx-docker-cert-deploy
+enable_one_letsencrypt_cert_for_all:  false    

roles/nginx-docker-cert-deploy/README.md

@@ -1,103 +1,158 @@
 # Nginx Docker Cert Deploy Role
 
-🎉 **Author**: Kevin Veen-Birkenbach ([veen.world](https://www.veen.world))
+🎉 **Author**: [Kevin Veen-Birkenbach](https://www.veen.world)
 
-This Ansible role simplifies the deployment of Let's Encrypt certificates into Docker Compose setups with Nginx. It ensures that certificates are copied, directories are created, and Nginx services are reloaded or restarted as needed.
+This Ansible role simplifies the deployment of **Let's Encrypt certificates** into **Docker Compose** setups with Nginx. It supports both **individual certificates per subdomain** and a **single wildcard certificate** for all subdomains.
 
 ---
 
 ## 🚀 **Features**
-
+- Automatically deploys **Let's Encrypt certificates** to Docker Compose setups.
-- Copies Let's Encrypt certificates to the target directory.
+- Supports both **single-domain certificates** and **one wildcard certificate** for all subdomains.
-- Automatically reloads or restarts Nginx services in all Docker Compose containers.
+- **Copies certificates** to the target directory inside the container.
-- Configures and manages a `systemd` service for automated deployment.
+- Automatically **reloads or restarts Nginx services** when certificates are updated.
-- Supports periodic execution via a `systemd` timer.
+- **Configures and manages a `systemd` service** for automated certificate deployment.
-- Handles dependent services like `systemd-notifier`.
+- **Includes a `systemd` timer** for scheduled renewals.
+- **Handles dependent services** like `systemd-notifier`.
 
 ---
 
-## 🔧 **Variables**
+## 📋 **Configuration Options**
 
-The following variables can be customized:
+### 🔹 **One Wildcard Certificate for All Subdomains**
-
+By default, each subdomain gets its own certificate. You can **enable a wildcard certificate** by setting:
-| Variable                          | Description                                    | Default Value                           |
-|-----------------------------------|------------------------------------------------|-----------------------------------------|
-| `cert_mount_directory`            | Target directory to mount certificates.        | `{{docker_compose_instance_directory}}/certs/` |
-| `nginx_docker_cert_deploy_script` | Path to the deployment script.                 | `{{path_administrator_scripts}}nginx-docker-cert-deploy.sh` |
-| `docker_compose_project_name`     | Name of the Docker Compose project.            | None (must be defined in playbook)      |
-| `on_calendar_deploy_certificates` | `systemd` timer schedule for certificate updates. | None (must be defined in playbook)      |
-
----
-
-## 📋 **Tasks Overview**
-
-### Main Tasks
-
-1. **Add Deployment Script**:
-   Copies the `nginx-docker-cert-deploy.sh` script to the administrator scripts directory.
-
-2. **Create Certificate Directory**:
-   Ensures the `cert_mount_directory` exists with proper permissions.
-
-3. **Configure Systemd Service**:
-   Deploys a `systemd` service file for the deployment process.
-
-4. **Include `systemd-timer` Role**:
-   Schedules automatic deployment tasks using a `systemd` timer.
-
-### Handlers
-
-- **Restart Service**:
-  Restarts the `nginx-docker-cert-deploy` service when configuration changes.
-
----
-
-## 📂 **File Structure**
-
-```
-roles/
-  nginx-docker-cert-deploy/
-    vars/
-      main.yml
-    handlers/
-      main.yml
-    files/
-      nginx-docker-cert-deploy.sh
-    tasks/
-      main.yml
-    templates/
-      nginx-docker-cert-deploy.service.j2
-    meta/
-      main.yml
-```
-
----
-
-## 📖 **Usage Example**
-
-Here's an example of how to use this role in your playbook:
 
 ```yaml
-- name: Deploy Let's Encrypt certificates to Docker Compose
+enable_one_letsencrypt_cert_for_all: true
-  hosts: all
+```
-  roles:
+
-    - role: nginx-docker-cert-deploy
+📌 **Pros & Cons of a Wildcard Certificate:**
-      vars:
+✅ **Improves performance** by reducing TLS handshakes.  
-        domain: "example.com"
+✅ **Simplifies certificate management** (one cert for all subdomains).  
-        docker_compose_instance_directory: "/home/administrator/docker-compose/nginx"
+⚠ **Requires manual DNS challenge setup** for Let's Encrypt.  
-        docker_compose_project_name: "nginx"
+⚠ **Needs additional configuration for automation** (see below).  
-        on_calendar_deploy_certificates: "daily"
+
+If enabled, update your inventory file and follow the **manual wildcard certificate setup** below.
+
+---
+
+## 🔧 **Tasks Overview**
+
+### **1️⃣ Main Tasks**
+1. **Add Deployment Script**  
+   - Copies `nginx-docker-cert-deploy.sh` to the administrator scripts directory.
+   
+2. **Create Certificate Directory**  
+   - Ensures `cert_mount_directory` exists with proper permissions.
+   
+3. **Configure `systemd` Service**  
+   - Deploys a `systemd` service file for the deployment process.
+   
+4. **Include `systemd-timer` Role**  
+   - Schedules automatic certificate deployment using a `systemd` timer.
+
+### **2️⃣ Handlers**
+- **Restart Nginx Service**  
+  - Restarts `nginx-docker-cert-deploy` whenever a certificate update occurs.
+
+---
+
+## **🔐 Wildcard Certificate Setup with Let's Encrypt**
+If you enabled `enable_one_letsencrypt_cert_for_all`, follow these steps to manually request a **wildcard certificate**.
+
+### **1️⃣ Run the Certbot Command 🖥️**
+```sh
+certbot certonly --manual --preferred-challenges=dns --agree-tos \
+--email administrator@primary_domain -d primary_domain -d "*.primary_domain"
+```
+
+### **2️⃣ Add DNS TXT Record for Validation 📜**
+Certbot will prompt you to add a DNS TXT record:
+```
+Please create a TXT record under the name:
+_acme-challenge.primary_domain.
+
+with the following value:
+9oVizYIYVGlZ3VtWQIKRS5UghyXiqGoUNlCtIE7LiA
+```
+➡ **Go to your DNS provider** and create a new **TXT record**:  
+   - **Host:** `_acme-challenge.primary_domain`  
+   - **Value:** `"9oVizYIYVGlZ3VtWQIKRS5UghyXiqGoUNlCtIE7LiA"`  
+   - **TTL:** Set to **300 seconds (or lowest possible)**  
+
+✅ **Verify the DNS record** before continuing:  
+```sh
+dig TXT _acme-challenge.primary_domain @8.8.8.8
+```
+
+### **3️⃣ Complete the Certificate Request ✅**
+Once the DNS changes have propagated, **press Enter** in the Certbot terminal.  
+If successful, Certbot will save the certificates under:  
+```
+/etc/letsencrypt/live/primary_domain/
+```
+- **fullchain.pem** → The certificate  
+- **privkey.pem** → The private key  
+
+---
+
+## **📂 File & Directory Structure**
+```sh
+roles/nginx-docker-cert-deploy/
+├── files/
+│   ├── nginx-docker-cert-deploy.sh  # Deployment script
+├── handlers/
+│   ├── main.yml  # Restart Nginx handler
+├── meta/
+│   ├── main.yml  # Dependencies
+├── tasks/
+│   ├── main.yml  # Main Ansible tasks
+├── templates/
+│   ├── nginx-docker-cert-deploy.service.j2  # Systemd service template
+├── vars/
+│   ├── main.yml  # Variable definitions
 ```
 
 ---
 
-## 🛠️ **Dependencies**
+## **🔧 Deploying Certificates into Docker Containers**
+The role **automates copying certificates** into Docker Compose setups.
 
-This role depends on:
+### **1️⃣ Deployment Script (`nginx-docker-cert-deploy.sh`)**
+This script:
+- **Copies certificates** to the correct container directory.
+- **Reloads Nginx** inside all running containers.
+- **Restarts containers if needed**.
 
-- `systemd-notifier`: Notifies about failures in the `systemd` service.
+**Usage:**
+```sh
+sh nginx-docker-cert-deploy.sh primary_domain /path/to/docker/compose
+```
+
+### **2️⃣ Systemd Service & Timer**
+The role includes a **`systemd` service** that runs the deployment script whenever certificates are updated.
+
+Example `nginx-docker-cert-deploy.service.j2`:
+```ini
+[Unit]
+Description=Let's Encrypt deploy to {{docker_compose_instance_directory}}
+OnFailure=systemd-notifier.cymais@%n.service
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/bash {{path_administrator_scripts}}/nginx-docker-cert-deploy.sh {{primary_domain}} {{docker_compose_instance_directory}}
+```
 
 ---
 
-Feel free to contribute, report issues, or suggest improvements! 😊
+## 🎯 **Summary**
+| Feature | Description |
+|---------|------------|
+| **Single-domain & wildcard support** | Use individual certs or a wildcard certificate |
+| **Automated renewal** | Cronjob or systemd timer ensures auto-renewals |
+| **Docker-ready** | Deploys certificates directly into Docker containers |
+| **Supports Nginx & Mailu** | Compatible with multiple services |
+| **Systemd integration** | Automates deployment via `systemd` |
 
+🚀 **Now your Nginx setup is fully automated and secured with Let's Encrypt!** 🎉
+```