How To Install Caddy on CentOS Stream 10

In this tutorial, we will show you how to install Caddy on CentOS Stream 10. Caddy has emerged as one of the most innovative web servers in recent years, offering numerous advantages for system administrators and developers alike. With its robust feature set, automatic HTTPS capabilities, and simplified configuration syntax, Caddy provides an excellent alternative to traditional web servers like Apache and Nginx. This comprehensive guide will walk you through the process of installing and configuring Caddy on CentOS Stream 10, covering everything from basic setup to advanced features and troubleshooting.

Understanding Caddy Web Server

Caddy is an open-source, lightweight web server written in Go. Unlike traditional web servers, Caddy was built from the ground up with security and ease of use in mind. One of its most notable features is automatic HTTPS, which enables your websites to serve content securely without manual certificate management.

Key Features of Caddy

Caddy offers several advantages that make it stand out from other web servers:

• Automatic HTTPS with Let’s Encrypt integration by default
• HTTP/2 and HTTP/3 support out of the box
• Simple, readable configuration syntax
• Built-in support for reverse proxying
• Advanced TLS features and security defaults
• Native JSON API for configuration
• Middleware capabilities for extending functionality

When compared to Apache and Nginx, Caddy might have a smaller market share, but its modern architecture and features make it particularly suitable for developers looking for simplicity without sacrificing capabilities. For static sites, dynamic applications, or as a reverse proxy, Caddy excels due to its performance and ease of configuration.

Prerequisites for Installing Caddy

Before proceeding with the installation, ensure that your CentOS Stream 10 environment meets the following requirements:

• A server running CentOS Stream 10 with at least 1GB RAM and 10GB storage
• A user with sudo privileges for administrative tasks
• A properly configured domain name pointing to your server (required for automatic HTTPS)
• Basic familiarity with terminal commands and Linux operations
• Open ports 80 and 443 in your firewall for HTTP and HTTPS traffic

It’s also recommended to update your system before proceeding:

sudo dnf update -y

This ensures that all system packages are up to date, reducing potential compatibility issues with new software installations.

Installation Methods Overview

There are several ways to install Caddy on CentOS Stream 10, each with its own advantages and considerations:

1. Official Repository Installation: The most straightforward method using the official Caddy repository, which provides automatic updates and integration with the system package manager.
2. Direct Binary Installation: Downloading and installing the Caddy binary directly, offering more control over the version and location.
3. Docker Installation: Running Caddy as a container, which provides isolation and simplified deployment in containerized environments.

The official repository method is recommended for most users as it simplifies updates and maintenance while ensuring you get an officially supported version of Caddy.

Method 1: Installing Caddy via Official Repository

The Caddy team maintains official packages for various Linux distributions, including Red Hat-based systems like CentOS Stream. Follow these steps to install Caddy using this method:

1. First, install the necessary dependencies:

sudo dnf install -y dnf-plugins-core

2. Add the official Caddy repository:

sudo dnf copr enable @caddy/caddy

3. Install Caddy using dnf:

sudo dnf install caddy

4. Verify the installation by checking the Caddy version:

caddy version

This should display the installed version of Caddy, confirming that the installation was successful. The repository installation automatically sets up Caddy as a systemd service, allowing you to manage it using standard systemd commands.

Method 2: Installing Caddy via Direct Download

If you prefer more control over the installation process or need a specific version of Caddy, you can download the binary directly:

1. Download the latest Caddy binary for Linux:

wget https://github.com/caddyserver/caddy/releases/latest/download/caddy_2.x.y_linux_amd64.tar.gz

Replace 2.x.y with the actual version number you want to install.

2. Extract the binary:

tar -xzf caddy_2.x.y_linux_amd64.tar.gz

3. Move the binary to a system directory:

sudo mv caddy /usr/local/bin/

4. Set the appropriate permissions:

sudo chmod +x /usr/local/bin/caddy
sudo setcap cap_net_bind_service=+ep /usr/local/bin/caddy

The second command allows Caddy to bind to privileged ports (80, 443) without running as root, which is a security best practice.

Method 3: Installing Caddy via Docker

For containerized environments, Docker provides a clean and isolated way to run Caddy:

1. Install Docker if you haven’t already:

sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker

2. Pull the official Caddy Docker image:

sudo docker pull caddy:latest

3. Create directories for Caddy configuration and data:

mkdir -p ~/caddy/config ~/caddy/data ~/caddy/site

4. Run Caddy as a container:

sudo docker run -d -p 80:80 -p 443:443 \
  -v ~/caddy/site:/srv \
  -v ~/caddy/config:/config \
  -v ~/caddy/data:/data \
  --name caddy caddy:latest

This command maps the necessary ports and volumes to your host system, allowing Caddy to serve content and store its configuration and certificate data.

Post-Installation Setup

After installing Caddy, you’ll need to perform some additional setup to ensure it runs correctly:

1. Create a dedicated user for Caddy (if not created automatically by the package):

sudo useradd -r -d /var/lib/caddy -M -s /sbin/nologin caddy

2. Set up the necessary directory structure:

sudo mkdir -p /etc/caddy /var/lib/caddy /var/log/caddy
sudo chown -R caddy:caddy /var/lib/caddy /var/log/caddy

3. Ensure proper file permissions:

sudo chown -R root:caddy /etc/caddy
sudo chmod 770 /var/lib/caddy

These steps create a secure environment for Caddy to operate, following the principle of least privilege by using a dedicated system user with limited permissions.

Configuring Firewall for Caddy

CentOS Stream 10 uses firewalld by default. To allow HTTP and HTTPS traffic, you’ll need to open the appropriate ports:

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

You can verify that the ports are open with:

sudo firewall-cmd --list-all

This should show that the http and https services are added to your active zone, allowing incoming traffic on ports 80 and 443.

Basic Caddy Configuration

Caddy uses a file called Caddyfile for its configuration. On CentOS Stream 10, this file is typically located at /etc/caddy/Caddyfile. Let’s create a basic configuration:

1. Open the Caddyfile for editing:

sudo nano /etc/caddy/Caddyfile

2. Add a basic configuration for serving static files:

example.com {
    root * /var/www/example.com
    file_server
    log {
        output file /var/log/caddy/example.com.log
    }
}

Replace example.com with your actual domain name. This configuration tells Caddy to:

• Serve files from the /var/www/example.com directory
• Enable the file server module
• Log access to a dedicated log file

3. Save the file and exit the editor.

4. Create the web root directory:

sudo mkdir -p /var/www/example.com
sudo chown -R caddy:caddy /var/www/example.com

5. Test the configuration:

sudo caddy validate --config /etc/caddy/Caddyfile

If the configuration is valid, you won’t see any errors.

Setting Up Caddy as a System Service

If you installed Caddy via the official repository, the systemd service should already be set up. Otherwise, you’ll need to create it manually:

1. Create a systemd service file:

sudo nano /etc/systemd/system/caddy.service

2. Add the following content:

[Unit]
Description=Caddy Web Server
Documentation=https://caddyserver.com/docs/
After=network.target network-online.target
Requires=network-online.target

[Service]
Type=notify
User=caddy
Group=caddy
ExecStart=/usr/local/bin/caddy run --config /etc/caddy/Caddyfile
ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=512
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

3. Save the file and exit the editor.

4. Enable and start the Caddy service:

sudo systemctl daemon-reload
sudo systemctl enable caddy
sudo systemctl start caddy

5. Check the status of the service:

sudo systemctl status caddy

This should show that Caddy is active and running. You can now manage Caddy using standard systemd commands like start, stop, restart, and status.

Creating Your First Website with Caddy

Now that Caddy is installed and configured, let’s create a simple website:

1. Create an index.html file in your web root:

sudo nano /var/www/example.com/index.html

2. Add some basic HTML content:

<!DOCTYPE html>
<html>
<head>
    <title>Welcome to my Caddy website!</title>
</head>
<body>
    <h1>Hello from Caddy on CentOS Stream 10!</h1>
    <p>This site is served using Caddy with automatic HTTPS.</p>
</body>
</html>

3. Save the file and exit the editor.

4. Set proper permissions:

sudo chown caddy:caddy /var/www/example.com/index.html

5. Navigate to your domain in a web browser.

If your domain is properly configured to point to your server, you should see your website being served over HTTPS automatically, with Caddy handling the certificate management behind the scenes.

Configuring Virtual Hosts in Caddy

To host multiple websites on a single server, you can configure virtual hosts in your Caddyfile:

1. Update your Caddyfile:

sudo nano /etc/caddy/Caddyfile

2. Add configurations for multiple domains:

example.com {
    root * /var/www/example.com
    file_server
    log {
        output file /var/log/caddy/example.com.log
    }
}

blog.example.com {
    root * /var/www/blog.example.com
    file_server
    log {
        output file /var/log/caddy/blog.example.com.log
    }
}

3. Create the directory for the second site:

sudo mkdir -p /var/www/blog.example.com
sudo chown -R caddy:caddy /var/www/blog.example.com

4. Reload Caddy to apply the changes:

sudo systemctl reload caddy

Each domain will now be served from its own directory, with Caddy automatically handling the routing based on the requested domain name.

Enabling HTTPS with Automatic SSL

One of Caddy’s standout features is automatic HTTPS. By default, Caddy will:

1. Automatically obtain and renew SSL certificates from Let’s Encrypt
2. Configure secure TLS settings
3. Redirect HTTP traffic to HTTPS
4. Handle all certificate management in the background

This happens automatically when you specify a domain name in your Caddyfile. To customize the HTTPS behavior, you can add more directives:

example.com {
    root * /var/www/example.com
    file_server
    tls admin@example.com {
        dns cloudflare apitoken
    }
}

The tls directive allows you to specify an email address for certificate notifications and optionally configure DNS providers for DNS-01 challenges, which are necessary for wildcard certificates.

Setting Up PHP with Caddy

To serve PHP applications with Caddy:

1. Install PHP and PHP-FPM:

sudo dnf install php php-fpm

2. Start and enable PHP-FPM:

sudo systemctl enable --now php-fpm

3. Update your Caddyfile:

example.com {
    root * /var/www/example.com
    php_fastcgi unix//run/php-fpm/www.sock
    file_server
}

4. Create a test PHP file:

sudo nano /var/www/example.com/info.php

5. Add PHP code:

<?php
phpinfo();

6. Reload Caddy:

sudo systemctl reload caddy

Navigate to https://example.com/info.php to verify that PHP is working correctly.

Using Caddy as a Reverse Proxy

Caddy makes an excellent reverse proxy for backend applications:

1. Update your Caddyfile:

api.example.com {
    reverse_proxy localhost:8080
}

This configuration forwards requests to api.example.com to a service running on port 8080.

For more complex setups, you can add load balancing:

api.example.com {
    reverse_proxy {
        to localhost:8080 localhost:8081 localhost:8082
        lb_policy round_robin
        health_path /health
        health_interval 10s
    }
}

This distributes traffic across multiple backend servers and includes health checks to ensure availability.

Advanced Caddy Features

Caddy offers numerous advanced features:

Basic Authentication:

example.com {
    root * /var/www/example.com
    file_server
    basic_auth /admin/* {
        admin JDJhJDE0JDFrLkpVRHlTUzc1SkRnTHZWN1VYZnVubVlOcWlIeVhLY25Ic3dCVC9OVjIuWnVadDdXakdP
    }
}

URL Rewriting:

example.com {
    root * /var/www/example.com
    file_server
    rewrite /old-page.html /new-page.html
}

Custom Error Pages:

example.com {
    root * /var/www/example.com
    file_server
    handle_errors {
        rewrite * /error.html
        file_server
    }
}

These features allow you to create sophisticated web server configurations with minimal effort.

Monitoring and Logging

Caddy provides comprehensive logging capabilities:

1. Configure logging in your Caddyfile:

example.com {
    root * /var/www/example.com
    file_server
    log {
        output file /var/log/caddy/access.log
        format json
    }
}

2. View logs using standard tools:

sudo tail -f /var/log/caddy/access.log

For system-level logs, you can use journalctl:

sudo journalctl -u caddy -f

This streams Caddy’s systemd logs in real-time, which is helpful for troubleshooting.

Upgrading Caddy

To upgrade Caddy when installed via the official repository:

sudo dnf update caddy

For binary installations, download the new version and replace the existing binary:

wget https://github.com/caddyserver/caddy/releases/latest/download/caddy_2.x.y_linux_amd64.tar.gz
tar -xzf caddy_2.x.y_linux_amd64.tar.gz
sudo systemctl stop caddy
sudo mv caddy /usr/local/bin/
sudo systemctl start caddy

Always back up your configuration before upgrading and check the release notes for any breaking changes.

Troubleshooting Common Issues

Permission Problems:
If Caddy can’t access files or bind to ports, check the permissions:

sudo setcap cap_net_bind_service=+ep /usr/local/bin/caddy
sudo chown -R caddy:caddy /var/www/example.com

Configuration Errors:
Validate your configuration before applying it:

sudo caddy validate --config /etc/caddy/Caddyfile

Certificate Issues:
If automatic HTTPS isn’t working, ensure:

• Your domain points to your server
• Ports 80 and 443 are open
• Caddy has write access to its storage directory

System Logs:
Check the logs for more detailed error messages:

sudo journalctl -u caddy -n 50

This shows the last 50 log entries from the Caddy service.

Congratulations! You have successfully installed Caddy. Thanks for using this tutorial for installing the Caddy web server on your CentOS Stream 10 system. For additional help or useful information, we recommend you check the official Caddy website.