Benjamin Diedrichsen
121 lines
3.2 KiB
Markdown
121 lines
3.2 KiB
Markdown
# 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)**:
|
|
```javascript
|
|
exec('caddy', { TLS: '' })
|
|
```
|
|
Caddy will automatically obtain SSL certificates from Let's Encrypt for your domain.
|
|
|
|
**Self-Signed for Testing**:
|
|
```javascript
|
|
exec('caddy', { TLS: 'internal' })
|
|
```
|
|
Uses Caddy's internal CA. Browsers will show security warnings.
|
|
|
|
**Custom Certificates**:
|
|
```javascript
|
|
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:
|
|
```bash
|
|
sudo systemctl start caddy
|
|
sudo systemctl stop caddy
|
|
sudo systemctl restart caddy
|
|
sudo systemctl status caddy
|
|
```
|
|
|
|
Reload configuration without downtime:
|
|
```bash
|
|
sudo systemctl reload caddy
|
|
```
|
|
|
|
Test configuration:
|
|
```bash
|
|
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](https://caddyserver.com/docs/)
|
|
- [Caddyfile Tutorial](https://caddyserver.com/docs/caddyfile-tutorial)
|