To configure wildcard subdomains for Let's Encrypt in Laravel Forge, you need to follow a specific process because Let's Encrypt wildcard certificates rely on DNS-01 challenge validation rather than the usual HTTP-01 challenge. This means instead of proving ownership of the domain via HTTP requests, you prove it by adding specific TXT records to your DNS provider.
Here is a detailed explanation of the steps involved:
Understanding Wildcard SSL Certificates and Let's Encrypt
A wildcard SSL certificate secures all subdomains of a given domain, such as \*.example.com, rather than protecting each subdomain individually. Let's Encrypt issues wildcard certificates only via DNS-01 challenge, which requires access to your DNS provider to add TXT records for validation.
Let's Encrypt wildcard certificates cover all subdomains at one level. For example, \*.example.com covers blog.example.com, shop.example.com, etc., but it does not cover sub-subdomains like api.blog.example.com.
Step 1: Prerequisites in Laravel Forge
- You must have your site set up in Laravel Forge.
- Your domain DNS must be managed by a DNS provider that Laravel Forge supports for automatic DNS challenge resolution, or you must have manual access to modify DNS TXT records.
- Your Forge account needs API credentials for your DNS provider if you want to automate the DNS challenge (supported DNS providers include DigitalOcean, Cloudflare, Route53 for AWS, etc.).
- Make sure you have permissions set to manage DNS records in your DNS provider.
Step 2: Add Your Site in Laravel Forge
In Laravel Forge, set up your site normally by adding your domain, for example, example.com. You should add both the root domain (example.com) and a wildcard subdomain entry (\*.example.com) when configuring the SSL certificate request.
Step 3: Request a Wildcard Let's Encrypt Certificate in Forge
When requesting the SSL certificate in Forge under the site management:
- Choose âLet's Encryptâ as the SSL provider.
- Specify your domain name with wildcards, for instance, `example.com, *.example.com`.
- Forge will detect that a wildcard certificate requires DNS validation and prompt you for API credentials for your DNS provider.
Step 4: Connect DNS Provider API in Forge
- Forge requires API credentials to automatically add the TXT records for DNS validation.
- Depending on your DNS provider, generate an API token or key with permissions to edit DNS records.
- Input this API credential into Laravel Forge when prompted, or add it in the âDNS Providerâ section if managing multiple domains.
- Forge supports several providers including DigitalOcean (Zone.Zone.Read and Zone.DNS.Edit permissions), Cloudflare (Zone.Zone.Read and Zone.DNS.Edit), and AWS Route53 (permissions such as route53:ChangeResourceRecordSets, route53:GetChange, route53:ListHostedZones).
Step 5: Forge Adds DNS TXT Record Automatically
Once Forge has your DNS API credentials, it will automatically create the necessary TXT record for the DNS-01 Let's Encrypt challenge under the `_acme-challenge` subdomain. This TXT record's content is generated by Let's Encrypt and used for domain ownership verification.
Step 6: Certificate Issuance and Installation
- After the DNS record is validated by Let's Encrypt, Forge will receive the wildcard certificate.
- Forge automatically installs the certificate on your server.
- The installed certificate will cover both the root domain and all subdomains matching the wildcard pattern.
Step 7: Nginx Configuration in Forge
Laravel Forge manages the Nginx configuration for your site. For wildcard certificates, Forge configures Nginx to listen to your domain and wildcard subdomains securely by linking the certificate files in the server block.
Usually, the Nginx config will include:
- ssl_certificate and ssl_certificate_key paths pointing to Let's Encrypt certificates.
- server_name directive listing `example.com` and `*.example.com`.
- TLS protocols and cipher suite configurations for security compliance.
Step 8: Renewal of Wildcard Certificates
Let's Encrypt certificates are valid for 90 days. Laravel Forge automatically handles renewal by periodically checking and renewing certificates before expiration.
Because the DNS-01 challenge requires TXT records, Forge relies on the DNS provider API to update the TXT records automatically again during renewal.
Manual DNS Validation Option (If API Integration Is Not Available)
If your DNS provider is not supported by Forge's automatic DNS challenge, or you prefer manual control, you can:
- Request the certificate manually by adding the `_acme-challenge` TXT records yourself.
- Forge will prompt the specific TXT record name and value.
- You need to log in to your DNS provider's control panel, create or update the TXT record accordingly.
- After propagation, confirm from Forge to proceed with certificate issuance.
- This manual step must be repeated for every renewal.
Important Notes and Best Practices
- The wildcard certificate will not cover the root domain alone, so explicitly include the root domain (`example.com`) in the certificate request list alongside `*.example.com`.
- For multiple levels of subdomains (e.g., `*.*.example.com`), Let's Encrypt wildcard certificates do not support this natively.
- Ensure your DNS TTL is low during validation to speed up propagation.
- If you use Cloudflare or similar proxy services, disable proxying for DNS validation if errors arise.
- Always test the HTTPS setup with wildcard subdomains after installation.
- Use strong TLS settings in your Nginx configuration as enforced by Forge.
Example Step-by-Step Summary
1. Add your site (example.com) in Forge.
2. Choose SSL Let's Encrypt and enter domain names as: `example.com, *.example.com`.
3. Provide API token for your DNS provider inside Forge.
4. Forge creates DNS TXT records automatically for `_acme-challenge.example.com`.
5. Let's Encrypt verifies TXT records and issues the wildcard certificate.
6. Forge installs the certificate on your Nginx server.
7. Nginx configuration is automatically adjusted for your wildcard domain.
8. The certificate is auto-renewed using the DNS-01 challenge via API.
Troubleshooting Common Issues
- If Forge fails to issue the wildcard certificate, confirm the DNS API token permissions are correct.
- Check that the TXT records appear in the DNS publicly using tools like `dig` or online DNS lookups.
- If DNS records are delayed, wait for propagation or lower DNS TTL temporarily.
- For multiple domains or complex setups, ensure all necessary domains are listed when requesting the certificate.
- Disable proxying service on DNS records for validation TXT entry when using Cloudflare.
- If renewal fails, check Forge and DNS logs for errors in API access or DNS record creation.
By following these steps, you can successfully configure wildcard subdomain SSL certificates with Let's Encrypt in Laravel Forge, securing all subdomains efficiently under a single certificate with automated management and renewal capabilities. This approach leverages Forge's integration with DNS providers for a smooth DNS-01 challenge process essential for wildcard certificates.
This detailed configuration ensures a scalable, secure, and manageable SSL setup for applications hosted via Laravel Forge using Let's Encrypt's free and trusted certification authority.