Post

Enabling Local HTTPS for Development and Debugging

Posted
By Joey
9 min read

Developing and debugging web applications often requires mirroring production environments as closely as possible. A crucial aspect of this parity is using HTTPS (Hypertext Transfer Protocol Secure), even in local development. While HTTP might suffice for basic local testing, many modern browser features, APIs, and security considerations mandate a secure context. This article explores various tools and methods to set up local HTTPS, including Nginx, Caddy, Puma-dev, and even a local Kubernetes environment with Cert-Manager.

Why Local HTTPS Matters

Beyond simply matching production, local HTTPS offers several key benefits:

  • Security Context for APIs: Many browser APIs (e.g., Geolocation, Service Workers, WebUSB, Payment Request API) are restricted to secure contexts. Developing with HTTPS locally ensures these features work as expected. 🔐
  • Preventing Mixed Content Issues: When parts of your application are served over HTTP and others over HTTPS, browsers can block the insecure content, leading to broken functionality or visual glitches.
  • Cookie Security: Secure cookies (those with the Secure attribute) are only sent over HTTPS connections. Using HTTPS locally ensures your cookie handling is accurate.
  • HSTS (HTTP Strict Transport Security): If your production site uses HSTS, browsers will enforce HTTPS for all subsequent connections. Developing over HTTP locally can lead to unexpected redirects or errors.
  • Realism: Testing your application under the same protocol as production helps uncover potential issues related to redirects, certificate handling, and overall network behavior early in the development cycle.

Tools for Local HTTPS

Let’s dive into some popular tools and how to configure them for local HTTPS.

Caddy: The Automatic HTTPS Champion

Caddy is a modern, open-source web server known for its simplicity and automatic HTTPS. It’s incredibly easy to set up for local development.

How it Works:

Caddy automatically provisions and manages TLS certificates for your local domains using its internal CA (Certificate Authority). The first time it does this, it’ll typically prompt you to install its root certificate into your system’s trust store. Once trusted, your browser will recognize certificates issued by Caddy as valid for your local domains.

Setup:

  1. Install Caddy: Refer to the official Caddy documentation for installation instructions specific to your operating system. For macOS, brew install caddy is common.

  2. Create a Caddyfile: Create a file named Caddyfile in your project root or a central location. Here’s a basic example for a local application running on localhost:3000:

    mylocalapp.test {
    tls internal
    reverse_proxy localhost:3000
}
    • mylocalapp.test: This is your custom local domain. You’ll need to configure your hosts file (or a local DNS resolver like dnsmasq) to point this domain to 127.0.0.1.
    • tls internal: This tells Caddy to automatically manage self-signed certificates for this domain and try to install its CA into your system’s trust store.
    • reverse_proxy localhost:3000: This forwards incoming HTTPS requests to your application running on localhost:3000 (or whatever port your app uses).

  3. Run Caddy: Navigate to the directory containing your Caddyfile in your terminal and run:

    1

    caddy run

    Caddy will prompt you to trust its root certificate. Accept it.

  4. Access your App: Now, you can access your application securely at https://mylocalapp.test.

Caddy’s Advantages:

  • Simplicity: Minimal configuration required for HTTPS.
  • Automatic Certificate Management: Caddy handles certificate generation, renewal, and trust store integration.
  • HTTP/2 and HTTP/3 support: Modern protocols out of the box.

Nginx with mkcert: Granular Control

Nginx is a powerful and widely used web server and reverse proxy. While it doesn’t have Caddy’s automatic HTTPS magic, you can easily pair it with a tool like mkcert to generate locally trusted certificates.

How it Works:

mkcert is a simple tool that creates locally-trusted development certificates. It does this by creating its own local CA and installing it into your system’s trust store. You then use these certificates with Nginx.

Setup:

  1. Install mkcert: Follow the installation instructions for mkcert. For macOS, brew install mkcert and mkcert -install are typical. This command will install a local CA into your system’s trust store.

  2. Generate Certificates with mkcert: Navigate to your project directory or a dedicated certificates folder and generate certificates for your local domain:

    1

    mkcert mylocalapp.test localhost 127.0.0.1

    This will create mylocalapp.test+2.pem (certificate) and mylocalapp.test+2-key.pem (private key) files.

  3. Install Nginx: Install Nginx according to your operating system’s instructions.

  4. Configure Nginx: Create or modify your Nginx configuration file (e.g., nginx.conf or a separate site configuration in sites-available/sites-enabled).

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

    server {
    listen 443 ssl;
    server_name mylocalapp.test;

    ssl_certificate /path/to/your/certs/mylocalapp.test+2.pem;
    ssl_certificate_key /path/to/your/certs/mylocalapp.test+2-key.pem;

    # Optional: Redirect HTTP to HTTPS
    listen 80;
    return 301 https://$host$request_uri;

    location / {
        proxy_pass http://localhost:3000; # Your application's HTTP address
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

    Replace /path/to/your/certs/ with the actual path where you saved your mkcert files.

  5. Update hosts file: Add an entry to your hosts file (e.g., /etc/hosts on Linux/macOS, C:\Windows\System32\drivers\etc\hosts on Windows):

    1

    127.0.0.1 mylocalapp.test

  6. Restart Nginx:

    1

    sudo nginx -s reload # or appropriate command for your system

  7. Access your App: You should now be able to access your application securely at https://mylocalapp.test.

Nginx Advantages:

  • Flexibility: Highly configurable for complex setups.
  • Performance: Excellent performance for serving static files and reverse proxying.
  • Widely Used: Extensive community support and resources.

Puma-dev: Ruby on Rails Simplicity

For Ruby on Rails developers, Puma-dev offers a streamlined solution for local HTTPS with custom domains.

How it Works:

Puma-dev acts as a local DNS server and HTTP/HTTPS proxy. It automatically resolves *.test domains (or other configurable TLDs) to your local machine, starts your Rails applications on demand, and provides HTTPS with self-signed certificates that are automatically trusted.

Setup:

  1. Install Puma-dev:

    1
2
3
4

    gem install puma # Ensure puma gem is installed in your app's Gemfile
brew install puma/puma/puma-dev # For macOS
sudo puma-dev -setup # Sets up necessary DNS and certificate configurations
puma-dev -install # Installs puma-dev as a user agent

  2. Link your Rails App: Navigate to your Rails application’s root directory and link it:

    1

    puma-dev link -n myrailsapp

    This will create a symlink in ~/.puma-dev (or wherever Puma-dev stores its linked apps).

  3. Access your App: Now, simply open your browser and navigate to https://myrailsapp.test. Puma-dev will automatically start your Rails application and serve it over HTTPS.

Puma-dev Advantages:

  • Rails-centric: Designed specifically for Ruby on Rails development.
  • Zero Configuration: Minimal setup for automatic app linking, custom domains, and HTTPS.
  • On-Demand Starting: Only starts your Rails app when accessed, saving resources.

Kubernetes Local Environment with Cert-Manager: Production Parity

For those developing applications intended for Kubernetes, setting up a local Kubernetes cluster (e.g., Minikube, Kind) with Cert-Manager offers the most production-like local HTTPS experience.

How it Works:

Cert-Manager is a native Kubernetes certificate management controller. It can issue certificates from various sources, including self-signed CAs, Vault, or public CAs like Let’s Encrypt. For local development, you’ll typically configure a ClusterIssuer or Issuer that uses a self-signed CA. Cert-Manager then watches Certificate resources and automatically provisions TLS secrets for your Ingresses.

Setup (using Minikube and a self-signed Issuer):

  1. Set up a Local Kubernetes Cluster: Install and start Minikube (or Kind):

    1

    minikube start

  2. Install Cert-Manager: Install Cert-Manager using Helm or kubectl manifests. It’s recommended to use Helm:

    1
2
3
4
5
6

    helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
    --namespace cert-manager \
    --create-namespace \
    --version v1.14.x # Use the latest stable version

    Verify the installation: kubectl get pods -n cert-manager

  3. Create a Self-Signed ClusterIssuer: This defines a cluster-wide CA that Cert-Manager will use to sign your development certificates. Create selfsigned-clusterissuer.yaml:

    1
2
3
4
5
6

    apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned-issuer
spec:
  selfSigned: {}

    Apply it: kubectl apply -f selfsigned-clusterissuer.yaml

  4. Create an Ingress and Certificate Resource: Assuming you have a deployment and service for your application, you’ll need an Ingress to expose it and a Certificate resource for Cert-Manager to manage its TLS.

    Example my-app-ingress.yaml:

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    cert-manager.io/cluster-issuer: selfsigned-issuer # Link to your ClusterIssuer
spec:
  rules:
  - host: myapp.local.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-app-service # Your application's service name
            port:
              number: 80
  tls: # Enable TLS for this Ingress
  - hosts:
    - myapp.local.com
    secretName: my-app-tls-secret # Cert-Manager will create this secret
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-app-certificate
  namespace: default # Or your application's namespace
spec:
  secretName: my-app-tls-secret
  dnsNames:
  - myapp.local.com
  issuerRef:
    name: selfsigned-issuer
    kind: ClusterIssuer

    Apply these resources: kubectl apply -f my-app-ingress.yaml

  5. Install an Ingress Controller: You’ll need an Ingress Controller (e.g., Nginx Ingress Controller) to actually route traffic. For Minikube, you can enable it with:

    1

    minikube addons enable ingress

  6. Update hosts file: Get the Minikube IP and add an entry to your hosts file:

    1
2

    minikube ip
# Example output: 192.168.49.2

    Add to your hosts file:

    1

    192.168.49.2 myapp.local.com

  7. Trust the Cert-Manager CA: Cert-Manager will create a CA certificate for its self-signed issuer. You’ll need to extract this and manually trust it in your operating system’s trust store. The exact steps vary, but it typically involves:

    • Getting the CA certificate from a Kubernetes secret (look for cert-manager-ca or similar, usually in the cert-manager namespace).
    • Decoding the base64-encoded certificate.
    • Importing it into your system’s trusted root certificates.

    Example (might vary):

    1

    kubectl get secret -n cert-manager cert-manager-webhook-ca -o jsonpath='{.data.ca\.crt}' | base64 --decode > cert-manager-ca.crt

    Then, import cert-manager-ca.crt into your OS.

  8. Access your App: Now, you can access your application securely at https://myapp.local.com.

Kubernetes with Cert-Manager Advantages:

  • Production Parity: Closest to how HTTPS is managed in a production Kubernetes environment.
  • Automated Certificate Lifecycle: Cert-Manager handles issuance, renewal, and secret management.
  • Scalable: Ideal for complex microservice architectures.

Conclusion

Setting up local HTTPS for development and debugging is a crucial step towards building robust and secure web applications. Whether you opt for the simplicity of Caddy, the granular control of Nginx with mkcert, the Rails-friendly Puma-dev, or the production-mirroring power of Kubernetes with Cert-Manager, each tool offers a viable path to a secure local development environment. By investing a little time in this setup, you’ll save yourself from many headaches related to browser security policies and ensure a smoother transition from development to production. Happy coding! 💻🔒🚀

Rails
This post is licensed under CC BY 4.0 by the author.