caddygo

README

CaddyGo

A simple Go library for managing Caddy server configurations through its admin API. CaddyGo provides a clean, intuitive interface to add, remove, and configure domains with automatic or custom TLS certificates, following Go best practices and clean architecture principles.

✨ Features

• Domain Management: Add and remove domains with ease
• Automatic TLS: Support for Let's Encrypt and other ACME providers
• Custom Certificates: Use your own TLS certificates
• Security Headers: Configurable security headers (HSTS, X-Frame-Options, etc.)
• Compression: Enable gzip and zstd compression
• Redirects: Support for www/non-www redirects
• Configuration Reload: Force Caddy to reload configurations
• Clean Architecture: Well-organized, maintainable codebase

📦 Installation

go get github.com/raghavyuva/caddygo

Quick Start

package main

import (
    "log"
    "github.com/raghavyuva/caddygo"
)

func main() {
    // Create a new client
    client := caddygo.NewClient("http://localhost:2019")
    
    // Configure domain options
    options := caddygo.DomainOptions{
        EnableSecurityHeaders: true,
        EnableHSTS:           true,
        EnableCompression:    true,
        RedirectMode:         "www_to_domain",
    }
    
    // Add a domain with automatic TLS
    err := client.AddDomainWithAutoTLS("example.com", "localhost", 8080, options)
    if err != nil {
        log.Fatal(err)
    }
    
    // Reload configuration
    err = client.Reload()
    if err != nil {
        log.Fatal(err)
    }
    
    log.Println("Domain configured successfully!")
}

Package Architecture

CaddyGo is organized into focused, single-responsibility modules:

caddygo/
├── types.go      # Type definitions and interfaces
├── client.go     # HTTP client and request handling
├── domain.go     # Domain management operations
├── tls.go        # TLS and certificate management
├── config.go     # Configuration helpers and utilities
└── caddygo.go    # Package entry point

API Reference

Core Types

Client

The main client for interacting with Caddy's admin API.

type Client struct {
    BaseURL    string        // Base URL of Caddy's admin API
    HTTPClient *http.Client  // HTTP client for API requests
}

DomainOptions

Configuration options for domain setup.

type DomainOptions struct {
    EnableSecurityHeaders bool   // Enable security-related HTTP headers
    EnableHSTS           bool   // Enable HTTP Strict Transport Security
    FrameOptions         string // X-Frame-Options header value
    EnableCompression    bool   // Enable gzip and zstd compression
    RedirectMode         string // Redirect behavior: "www_to_domain" or "domain_to_www"
}

Client Methods

NewClient

Creates a new Caddy API client.

func NewClient(baseURL string) *Client

Parameters:

• baseURL: The base URL of Caddy's admin API (defaults to "http://localhost:2019" if empty)

Returns: A configured Client instance

AddDomainWithAutoTLS

Adds a domain with automatic TLS configuration using Let's Encrypt or other ACME providers.

func (c *Client) AddDomainWithAutoTLS(domain, target string, targetPort int, options DomainOptions) error

Parameters:

• domain: The domain name to configure (e.g., "example.com")
• target: The target hostname or IP address
• targetPort: The target port number
• options: Configuration options for security, compression, and redirects

Returns: Error if configuration fails

AddDomainWithTLS

Adds a domain with a custom TLS certificate.

func (c *Client) AddDomainWithTLS(domain, target string, targetPort int, certificate, privateKey string, options DomainOptions) error

Parameters:

• domain: The domain name to configure
• target: The target hostname or IP address
• targetPort: The target port number
• certificate: PEM-encoded certificate content
• privateKey: PEM-encoded private key content
• options: Configuration options

Returns: Error if configuration fails

DeleteDomain

Removes a domain configuration and all associated routes, TLS policies, and automation rules.

func (c *Client) DeleteDomain(domain string) error

Parameters:

• domain: The domain name to remove

Returns: Error if deletion fails

Reload

Forces a reload of the Caddy configuration with cache invalidation.

func (c *Client) Reload() error

Returns: Error if reload fails

Usage Examples

Basic Domain Setup with Auto TLS

client := caddygo.NewClient("http://localhost:2019")

options := caddygo.DomainOptions{
    EnableSecurityHeaders: true,
    EnableHSTS:           true,
    EnableCompression:    true,
}

err := client.AddDomainWithAutoTLS("myapp.com", "localhost", 3000, options)
if err != nil {
    log.Fatalf("Failed to configure domain: %v", err)
}

err = client.Reload()
if err != nil {
    log.Fatalf("Failed to reload config: %v", err)
}

Custom Certificate Configuration

certificate := `-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKoK/OvH8T5TMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
BAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX
aWRnaXRzIFB0eSBMdGQwHhcNMTkwMzI2MTIzNDU5WhcNMjAwMzI1MTIzNDU5WjBF
MQswCQYDVQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50
ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
CgKCAQEAu1SUU7/3KryQigDTTw8cFDIehIUWqqK9t20Df1StvAhx3Xmddp/Wm3H
-----END CERTIFICATE-----`

privateKey := `-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7VJTUt9Us8cKj
MzEfYyjiWA4R4/M2bS1GB4t7NXp98C3SC6dVMvDuictGeurT8jNbvJZHtCSuYEvu
NMoSfm76oqFvAp8Gy0iz5sxjZmSnXyCdPEovGhLa0VzMaQ8s+CLOyS56YyCFGeJZ
-----END PRIVATE KEY-----`

options := caddygo.DomainOptions{
    EnableSecurityHeaders: true,
    EnableHSTS:           true,
    FrameOptions:          "SAMEORIGIN",
    EnableCompression:     true,
}

err := client.AddDomainWithTLS("secure.myapp.com", "localhost", 8443, certificate, privateKey, options)

Bulk Domain Management

domains := []struct {
    name   string
    target string
    port   int
}{
    {"api.myapp.com", "localhost", 3001},
    {"admin.myapp.com", "localhost", 3002},
    {"cdn.myapp.com", "localhost", 3003},
}

for _, d := range domains {
    options := caddygo.DomainOptions{
        EnableSecurityHeaders: true,
        EnableCompression:     true,
        RedirectMode:          "www_to_domain",
    }
    
    err := client.AddDomainWithAutoTLS(d.name, d.target, d.port, options)
    if err != nil {
        log.Printf("Failed to add domain %s: %v", d.name, err)
        continue
    }
    
    log.Printf("Successfully configured domain: %s", d.name)
}

// Reload all configurations at once
err := client.Reload()
if err != nil {
    log.Fatalf("Failed to reload configuration: %v", err)
}

Domain Cleanup

// Remove a specific domain
err := client.DeleteDomain("old.example.com")
if err != nil {
    log.Printf("Failed to remove domain: %v", err)
}

// Remove multiple domains
domainsToRemove := []string{"staging.example.com", "test.example.com"}
for _, domain := range domainsToRemove {
    err := client.DeleteDomain(domain)
    if err != nil {
        log.Printf("Failed to remove %s: %v", domain, err)
    }
}

// Reload to apply changes
err = client.Reload()

Configuration Options

Security Headers

options := caddygo.DomainOptions{
    EnableSecurityHeaders: true,
    EnableHSTS:           true,
    FrameOptions:          "DENY", // Options: "DENY", "SAMEORIGIN", "ALLOW-FROM"
}

Compression

options := caddygo.DomainOptions{
    EnableCompression: true, // Enables both gzip and zstd compression
}

Redirects

options := caddygo.DomainOptions{
    RedirectMode: "www_to_domain", // Options: "www_to_domain", "domain_to_www"
}

Error Handling

CaddyGo provides descriptive errors for various failure scenarios:

err := client.AddDomainWithAutoTLS("example.com", "localhost", 8080, options)
if err != nil {
    switch {
    case strings.Contains(err.Error(), "failed to get current config"):
        log.Println("Unable to connect to Caddy admin API")
    case strings.Contains(err.Error(), "failed to marshal"):
        log.Println("Configuration serialization error")
    case strings.Contains(err.Error(), "failed to update config"):
        log.Println("Failed to update Caddy configuration")
    default:
        log.Printf("Unexpected error: %v", err)
    }
    return
}

Requirements

• Go: 1.21 or later
• Caddy: v2 with admin API enabled
• Network: Access to Caddy's admin endpoint

Testing

Run the test suite:

go test -v

Run with coverage:

go test -cover

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Caddy - the modern web server
• Following Go best practices and clean architecture principles
• Inspired by the need for a clean, maintainable Caddy management library
• Reference - https://github.com/migetapp/caddy-api-client

---

Made with ❤️ for the Go community

Documentation

Overview

Package caddygo provides a Go client for interacting with Caddy's admin API. It allows you to manage domains, TLS certificates, and server configurations programmatically through a clean and intuitive interface.

Index

• type Client
  • func NewClient(baseURL string) *Client
  • func (c *Client) AddDomainWithACME(domain, target string, targetPort int, options DomainOptions) error
  • func (c *Client) AddDomainWithAutoTLS(domain, target string, targetPort int, options DomainOptions) error
  • func (c *Client) AddDomainWithTLS(domain, target string, targetPort int, certificate, privateKey string, ...) error
  • func (c *Client) DeleteDomain(domain string) error
  • func (c *Client) Reload() error
• type DomainOptions

Types

type Client

type Client struct {
	BaseURL    string
	HTTPClient *http.Client
}

Client represents a client for interacting with Caddy's admin API. It provides methods to manage domains, TLS certificates, and server configurations.

func NewClient

func NewClient(baseURL string) *Client

NewClient creates a new Caddy API client. If baseURL is empty, it defaults to "http://localhost:2019".

func (*Client) AddDomainWithACME

func (c *Client) AddDomainWithACME(domain, target string, targetPort int, options DomainOptions) error

AddDomainWithACME adds a domain with explicit ACME policy configuration. This approach uses non-on-demand ACME policies for more controlled certificate management.

Parameters:

• domain: The domain name to configure (e.g., "example.com")
• target: The target hostname or IP address
• targetPort: The target port number
• options: Configuration options for security headers, compression, and redirects

Returns an error if the configuration fails.

func (*Client) AddDomainWithAutoTLS

func (c *Client) AddDomainWithAutoTLS(domain, target string, targetPort int, options DomainOptions) error

AddDomainWithAutoTLS adds a domain with automatic TLS configuration. It configures the domain to proxy requests to the specified target and enables automatic certificate management through Let's Encrypt or other ACME providers.

Parameters:

• domain: The domain name to configure (e.g., "example.com")
• target: The target hostname or IP address
• targetPort: The target port number
• options: Configuration options for security headers, compression, and redirects

Returns an error if the configuration fails.

func (*Client) AddDomainWithTLS

func (c *Client) AddDomainWithTLS(domain, target string, targetPort int, certificate, privateKey string, options DomainOptions) error

AddDomainWithTLS adds a domain with a custom TLS certificate. It configures the domain to proxy requests to the specified target using the provided certificate and private key.

Parameters:

• domain: The domain name to configure (e.g., "example.com")
• target: The target hostname or IP address
• targetPort: The target port number
• certificate: PEM-encoded certificate content
• privateKey: PEM-encoded private key content
• options: Configuration options for security headers, compression, and redirects

Returns an error if the configuration fails.

func (*Client) DeleteDomain

func (c *Client) DeleteDomain(domain string) error

DeleteDomain removes a domain configuration from Caddy. It removes all routes, TLS policies, and automation rules associated with the domain.

Parameters:

• domain: The domain name to remove (e.g., "example.com")

Returns an error if the deletion fails.

func (*Client) Reload

func (c *Client) Reload() error

Reload forces a reload of the Caddy configuration. This method fetches the current configuration and sends it back to Caddy with cache invalidation headers to ensure the configuration is reloaded.

Returns an error if the reload fails.

type DomainOptions

type DomainOptions struct {
	// EnableSecurityHeaders enables security-related HTTP headers
	EnableSecurityHeaders bool
	// EnableHSTS enables HTTP Strict Transport Security header
	EnableHSTS bool
	// FrameOptions sets the X-Frame-Options header value (e.g., "DENY", "SAMEORIGIN")
	FrameOptions string
	// EnableCompression enables gzip and zstd compression
	EnableCompression bool
	// RedirectMode sets redirect behavior: "www_to_domain" or "domain_to_www"
	RedirectMode string
}

DomainOptions contains configuration options for domain setup. It allows customization of security headers, compression, and redirect behavior.