Stop Self-Signing: Use Let's Encrypt for Localhost SSL

Hey Devs! 👋

We’ve all felt the friction of local development not quite matching production, especially when it comes to HTTPS. You're building a modern SPA or testing Cloudflare Workers, and you need that secure context (https://) for certain APIs to function. While Cloudflare beautifully handles SSL for your live sites, your localhost is often left in the insecure http:// world, leading to warnings and features that just don't work.

The solution is to use a valid, browser-trusted SSL certificate on your local machine. But the process needs to be simple and, most importantly, automated. Manually renewing a certificate every 90 days is a chore we're all bound to forget.

This guide will show you the definitive "set it and forget it" method for domains managed by Cloudflare: using Certbot's Cloudflare DNS plugin. This approach automates the entire process, including renewals, so you can focus on coding.

How Automated DNS Verification Works

To issue a certificate, the Let's Encrypt Certificate Authority needs to verify you actually own the domain. For wildcard certificates, this is done using a "DNS challenge," where you prove ownership by creating a specific DNS TXT record.

While you could do this by hand, it's tedious. This is where the plugin shines. You give Certbot a special Cloudflare API token, and it handles the entire process for you:

1. Certbot tells Cloudflare's API to create the temporary TXT record.
2. It waits a few seconds for the record to go live.
3. It tells Let's Encrypt to verify the record.
4. Once verified, it automatically deletes the temporary record, leaving your DNS clean.

This all happens in seconds, without you ever having to log into the Cloudflare dashboard. It's the key to making certificate renewals completely automatic.

Prerequisites

• An Ubuntu Server: To run Certbot.
• A Domain Name Using Cloudflare DNS: Your domain's nameservers must be pointing to Cloudflare.
• A Cloudflare API Token: We will create this in the first step.
• sudo Privileges on the Ubuntu server.

Step 1: Create a Scoped Cloudflare API Token

First, we'll create a secure API token that only has permission to edit DNS records for our specific domain. This is much safer than using a global API key.

1. Log in to your Cloudflare dashboard.
2. Go to My Profile > API Tokens.
3. Click Create Token.
4. Find the "Edit zone DNS" template and click Use template.
5. Give your token a descriptive name, like "Certbot DNS-Challenge".
6. Under Permissions, ensure "Zone" - "DNS" - "Edit" is selected.
7. Under Zone Resources, select "Include" - "Specific zone" and choose the domain you want the certificate for. This is a critical security step.
8. Click Continue to summary, and then Create Token.
9. Copy the generated API token immediately! You will not see it again. Store it somewhere safe for the next step.

Step 2: Install Certbot and the Cloudflare DNS Plugin

Now, on your Ubuntu server, let's install Certbot and the specific plugin that allows it to communicate with Cloudflare's API.

sudo apt update
sudo apt install certbot python3-certbot-dns-cloudflare -y

Step 3: Securely Store Your Cloudflare API Token

We need to place the API token on the server where Certbot can find it. For security, we'll create a credentials file and lock down its permissions so only the root user can read it.

1. Create a dedicated directory for Certbot secrets.
   

   sudo mkdir -p /etc/letsencrypt/secrets/
   

2. Use a text editor to create a new file for your credentials.
   

   sudo nano /etc/letsencrypt/secrets/cloudflare.ini
   

3. Add the following line to the file, pasting the API token you copied from Step 1.
   

   # Cloudflare API token used by Certbot for DNS validation
   dns_cloudflare_api_token = YOUR_CLOUDFLARE_API_TOKEN_HERE
   

4. Save and close the file (Ctrl+X, then Y, then Enter).

5. Crucially, set the file permissions to prevent any other users on the system from accessing your API token.
   

   sudo chmod 600 /etc/letsencrypt/secrets/cloudflare.ini
   

Step 4: Generate the Wildcard Certificate

With everything in place, we can now run the Certbot command. It will use the plugin and credentials file to perform the automated DNS challenge.

Remember to replace your_domain.com with your actual domain name.

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/secrets/cloudflare.ini \
  --agree-tos \
  --email [e-mail] \
  -d your_domain.com \
  -d "*.your_domain.com"

Let's review the flags:

• certonly: Only get the certificate; do not install it in a webserver.
• --dns-cloudflare: Specifies that we are using the Cloudflare plugin.
• --dns-cloudflare-credentials: Points to our secure credentials file.
• --agree-tos and --email: Pre-agrees to the terms and provides a renewal email, allowing the command to run non-interactively.
• -d: Specifies the domain names to include in the certificate.

Certbot will now perform the automated challenge. Once complete, you will see a success message, and your certificate files will be available in /etc/letsencrypt/live/your_domain.com/.

Step 5: Using the Certificate and Verifying Auto-Renewal

You can now copy the fullchain.pem and privkey.pem files to your local machine and configure your development web server (e.g., Nginx, Node.js, Docker).

The best part is that the Certbot package on Ubuntu automatically sets up a systemd timer to run certbot renew twice a day. This command checks all certificates and automatically renews any that are nearing expiration using the same plugin method.

You can confirm that the renewal process is configured correctly by running a "dry run":

sudo certbot renew --dry-run

If the dry run completes without errors, you are all set. Your wildcard certificate will now renew itself automatically, providing a truly hands-off solution.

Conclusion

By using Certbot's Cloudflare DNS plugin, you eliminate manual work and the risk of forgetting to renew your local SSL certificates. This robust, automated setup lets you perfectly mirror your production environment's security, so you can focus on what you actually want to be doing: building great applications.

Happy (and secure) coding! 🚀