SSL Certificate Setup Guide

Prerequisites

SSL certificates in this system are automatically provisioned using Caddy's ACME integration with Cloudflare DNS challenges. This requires:

1. Cloudflare API Token (REQUIRED)

You MUST have a Cloudflare API token configured for SSL certificates to work. Without this, Caddy cannot provision SSL certificates.

Creating a Cloudflare API Token

1. Log in to your Cloudflare account
2. Go to "My Profile" → "API Tokens"
3. Click "Create Token"
4. Use the "Edit zone DNS" template or create a custom token with these permissions:
   • Zone → DNS → Edit
   • Zone → Zone → Read
5. Select the specific zones (domains) you want to manage
6. Copy the generated token

Configuring the Token in the System

1. Navigate to Local → Caddy in the dashboard
2. Click on the "Settings" tab
3. Paste your Cloudflare API Token in the "Cloudflare API Token" field
4. Set your ACME email address (for Let's Encrypt notifications)
5. Save the settings

How SSL Certificates Work

1. When you add a new server/route, Caddy is configured with the domain

2. During the sync process, if a Cloudflare token is present:

   • Caddy sets up ACME automation policies
   • It uses Cloudflare DNS challenges to verify domain ownership
   • Let's Encrypt issues the certificate
   • The certificate is automatically renewed before expiration

3. If no Cloudflare token is configured:

   • NO SSL certificates will be created
   • Your sites will only be accessible via HTTP
   • The SSL status will show "No SSL" or remain in "Checking" state

Troubleshooting

SSL Status Shows "Checking" Forever

• Verify that a Cloudflare API token is configured in Caddy settings
• Check that the domain is actually managed by Cloudflare
• Ensure the API token has the correct permissions

"No certificate found" Errors

• This is normal for new domains before the certificate is issued
• Certificate provisioning can take 1-5 minutes after adding a domain
• Check Caddy logs at /logs/caddy.log for ACME errors

Certificate Not Creating for New Domains

1. Confirm Cloudflare API token is set in Caddy settings
2. Verify the domain's DNS is managed by Cloudflare
3. Check that the domain has been synced to Caddy (click "Sync" button)
4. Wait 5 minutes for the ACME process to complete
5. Check Caddy logs for any ACME challenges failures

Important Notes

• Local/Private domains (like *.local or private IP addresses) cannot get public SSL certificates
• Each certificate covers both the domain and its wildcard (e.g., example.dev and *.example.dev)
• Certificates are stored in Caddy's data directory and persist across restarts
• Certificate renewal is automatic and happens ~30 days before expiration

DNS Requirements

For SSL certificates to work:

1. The domain must exist in Cloudflare DNS
2. The Cloudflare API token must have access to that zone
3. The DNS records don't need to point to your server (DNS challenge only verifies control)

Security Best Practices

• Store the Cloudflare API token securely
• Use a token with minimal permissions (only DNS edit for specific zones)
• Regularly rotate your API tokens
• Monitor certificate expiration dates (though auto-renewal should handle this)