ansiblings/packages/cubes-core/cubes/caddy/base

caddy

Install Caddy webserver

Purpose

This cube installs Caddy, a modern, powerful web server with automatic HTTPS that's designed to be easy to use and configure.

What is Caddy?

Caddy is a next-generation web server that stands out for its simplicity and built-in security:

• Automatic HTTPS: Automatically obtains and renews SSL/TLS certificates from Let's Encrypt
• Modern HTTP features: HTTP/2, HTTP/3 (QUIC) support out of the box
• Simple configuration: Human-readable Caddyfile format
• Reverse proxy: Easy proxying to backend applications
• Static file serving: Fast and efficient static site hosting
• Zero-downtime reloads: Update config without dropping connections

What This Cube Does

1. Adds Caddy's official repository

   • Installs required dependencies (debian-keyring, apt-transport-https, curl)
   • Downloads and installs Caddy's GPG signing key
   • Configures APT to use Caddy's official stable repository

2. Installs Caddy

   • Installs the latest stable version of Caddy
   • Sets up the Caddy service

3. Configures TLS

   • Creates a Caddyfile with a reusable TLS snippet
   • Configures TLS based on the TLS parameter

Configuration

Parameters

• TLS (string, default: '')
  • TLS certificate configuration
  • Options:
    • '' (empty string) - Automatic HTTPS with Let's Encrypt (recommended)
    • 'internal' - Use Caddy's internal CA for self-signed certs (testing only)
    • '/path/to/cert /path/to/key' - Provide custom certificate paths

Dependencies

None - this cube can run standalone.

TLS Configuration Examples

Automatic HTTPS (Production):

exec('caddy', { TLS: '' })

Caddy will automatically obtain SSL certificates from Let's Encrypt for your domain.

Self-Signed for Testing:

exec('caddy', { TLS: 'internal' })

Uses Caddy's internal CA. Browsers will show security warnings.

Custom Certificates:

exec('caddy', { TLS: '/etc/ssl/certs/mycert.pem /etc/ssl/private/mykey.pem' })

Use your own certificate and private key files.

Post-Installation

The Caddyfile is created at /etc/caddy/Caddyfile with a reusable TLS snippet:

(tls_cert) {
    tls {TLS}
}

Other cubes (like caddy-spa) can import this snippet with import tls_cert.

Managing Caddy

Start/stop/restart Caddy:

sudo systemctl start caddy
sudo systemctl stop caddy
sudo systemctl restart caddy
sudo systemctl status caddy

Reload configuration without downtime:

sudo systemctl reload caddy

Test configuration:

caddy validate --config /etc/caddy/Caddyfile

Common Use Cases

• Reverse proxy for Node.js/Python/Go apps
• Static website hosting
• API gateway
• Load balancer
• SSL/TLS termination

Notes

• Caddy runs on ports 80 (HTTP) and 443 (HTTPS) by default
• Ensure these ports are open in your firewall (UFW)
• For automatic HTTPS, your domain must point to your server's IP
• Caddy automatically redirects HTTP to HTTPS when using automatic HTTPS

Additional Resources

• Caddy Documentation
• Caddyfile Tutorial