Alpine Caddy Docker Image

Alpine Caddy Docker

A lightweight, secure, and flexible Docker image for Caddy server based on Alpine Linux. This setup provides an easy way to deploy Caddy with custom plugins, configurations, and static content.

Features

This Docker setup comes with several powerful features that make it ideal for both development and production environments:

• Based on lightweight Alpine Linux
• Support for custom Caddy plugins
• Automatic HTTPS with Let's Encrypt
• Security-focused configuration
• Volume persistence for configurations and certificates
• Easy customization through environment variables
• Support for multiple architectures (amd64, arm64, armv7, armv6)

Quick Start

The fastest way to get started is using docker-compose:

# Clone the repository
git clone https://github.com/hhftechnology/alpine-caddy
cd alpine-caddy

# Start the server
docker compose up -d

Visit http://localhost to see the default welcome page.

Directory Structure

The repository follows a clear structure for easy navigation:

📁 Project Root
├── Dockerfile              # Base Dockerfile
├── docker-compose.yml      # Docker Compose configuration
└── rootfs                  # Root filesystem overlay
    ├── etc
    │   ├── caddy          # Caddy configuration
    │   │   └── Caddyfile  # Default Caddyfile
    │   └── entrypoint.d   # Startup scripts
    ├── usr/local/bin      # Executables
    └── var/www            # Default web root

Configuration

Basic Configuration

The default Caddyfile provides a secure starting point:

{
    admin off
    persist_config off
}

:80 {
    root * /var/www
    file_server
    log {
        output stdout
        format json
    }
}

Custom Configuration

Create your own Caddyfile by mounting a volume:

services:
  caddy:
    volumes:
      - ./my-caddyfile:/etc/caddy/Caddyfile

Environment Variables

The image supports several environment variables:

• USER: The user to run Caddy (default: "caddy")
• PLUGINS: Array of Caddy plugins to install
• XDG_CONFIG_HOME: Config directory (default: /config)
• XDG_DATA_HOME: Data directory (default: /data)

Adding Plugins

You can add Caddy plugins in two ways:

1. Using environment variables in docker-compose.yml:

services:
  caddy:
    environment:
      - PLUGINS=["github.com/gamalan/caddy-tlsredis", "github.com/greenpau/caddy-auth-jwt"]

2. Creating a custom Dockerfile:

FROM hhftechnology/alpine-caddy:latest

ENV PLUGINS=( \
    "github.com/gamalan/caddy-tlsredis" \
    "github.com/greenpau/caddy-auth-jwt" \
)

RUN bash -c '/usr/local/bin/caddy-install.sh'

Common Use Cases

Static Website Hosting

Host a static website with automatic HTTPS:

example.com {
    root * /var/www
    file_server
    encode gzip
    tls your@email.com
}

Reverse Proxy

Set up a reverse proxy to your backend services:

api.example.com {
    reverse_proxy localhost:8080
    tls your@email.com
}

PHP Website

Host a PHP website using FastCGI:

example.com {
    root * /var/www
    php_fastcgi php-fpm:9000
    file_server
    tls your@email.com
}

Docker Compose configuration:

services:
  caddy:
    image: hhftechnology/alpine-caddy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./www:/var/www
    depends_on:
      - php-fpm

  php-fpm:
    image: php:8-fpm-alpine
    volumes:
      - ./www:/var/www

Multiple Sites

Host multiple sites with different configurations:

site1.example.com {
    root * /var/www/site1
    file_server
    tls your@email.com
}

site2.example.com {
    root * /var/www/site2
    file_server
    tls your@email.com
}

WebSocket Support

Enable WebSocket proxying:

ws.example.com {
    reverse_proxy /ws localhost:8080
    tls your@email.com
}

Security Considerations

The image includes several security enhancements:

1. Runs as non-root user (caddy)
2. Admin API disabled by default
3. Configuration persistence disabled
4. Minimal base image
5. Regular security updates

Additional security recommendations:

1. Use specific versions instead of 'latest' tag
2. Regularly update the image
3. Implement rate limiting for production
4. Use secure headers

Example secure headers configuration:

example.com {
    header {
        # Enable HTTP Strict Transport Security (HSTS)
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        
        # Prevent clickjacking attacks
        X-Frame-Options "SAMEORIGIN"
        
        # Help prevent XSS attacks
        X-XSS-Protection "1; mode=block"
        
        # Prevent MIME-sniffing
        X-Content-Type-Options "nosniff"
        
        # Referrer policy
        Referrer-Policy "strict-origin-when-cross-origin"
        
        # Remove Server header
        -Server
    }
    
    root * /var/www
    file_server
}

Performance Optimization

Optimize your Caddy server for production:

1. Enable compression:

encode gzip

2. Configure caching:

header Cache-Control "public, max-age=3600"

3. Use HTTP/3:

{
    servers {
        protocol {
            experimental_http3
        }
    }
}

Monitoring and Logging

Enable structured logging for better observability:

{
    log {
        output stdout
        format json
        level INFO
    }
}

For production monitoring, consider adding Prometheus metrics:

metrics.example.com {
    metrics
    basicauth {
        metrics-user JDJhJDE0JE91S1FrN0Z0VEsyR2xnUmZJMnQuL2VtT29qYWZ3WWFzYkY1bVI1Qi9JS1RBc2hXWEdpT0ph
    }
}

Troubleshooting

Common issues and solutions:

1. Permission errors:

   • Check volume permissions
   • Ensure correct user ownership

2. SSL certificate issues:

   • Verify DNS records
   • Check domain accessibility
   • Ensure ports 80/443 are accessible

3. Plugin installation failures:

   • Verify plugin compatibility
   • Check for build dependencies
   • Examine build logs

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

This project is licensed under the MIT License.

Support

For support:

• Open an issue on GitHub
• Join our community discussions
• Check the documentation

Remember to always check for the latest version and updates on our GitHub repository.