HUB
Sign inSign up

oaklight/caddy

By oaklight

•Updated 2 days ago

Caddy built with DNS, cache, Trojan and S3 certificate-storage plugins.

Image
0

946

oaklight/caddy repository overview

⁠Caddy with plugins

Caddy compiled from source with a fixed plugin set, published to Docker Hub as two image flavours: a scratch image that carries only the binary, and an Alpine image that runs as a container. CI tracks upstream Caddy releases, so a new Caddy version is built within a day of its release.

⁠Plugins

PluginBuild flagProvides
huaweicloudWITH_HUAWEICLOUD=trueHuawei Cloud DNS provider
cloudflareWITH_CLOUDFLARE=trueCloudflare DNS provider
dnspodWITH_DNSPOD=trueDNSPod DNS provider
alidnsWITH_ALIDNS=trueAlibaba Cloud DNS provider
cacheWITH_CACHE=trueServer-side HTTP cache (cache-handler)
s3-storageWITH_S3_STORAGE=trueS3-compatible certificate storage (certmagic-s3)
trojanWITH_TROJAN=trueTrojan proxy protocol

⁠Variants and tags

v{version} is the upstream Caddy version, for example v2.11.9.

VariantPluginsDescriptive tagShort alias
defaulthuaweicloud, cache, s3-storagev{version}-huaweicloud-cache-s3v{version}-default
fullall sevenv{version}-huaweicloud-cloudflare-dnspod-alidns-cache-s3-trojanv{version}-full

Each tag exists twice: the binary image uses the tag as listed, the runtime image appends -alpine. The descriptive tag and the short alias point at the same image, so both naming schemes stay valid.

latest and latest-alpine are only moved when a manual run passes update_latest: true, so a scheduled build cannot silently change what latest points at.

Both variants are multi-arch: linux/amd64 and linux/arm64.

The binary image is a scratch image. Extract the binary from it:

docker create --name caddy-extract oaklight/caddy:v2.11.9-huaweicloud-cache-s3
docker cp caddy-extract:/caddy ./caddy
docker rm caddy-extract

⁠Run

docker run -d \
  --name caddy \
  -p 80:80 -p 443:443 -p 443:443/udp \
  -v /path/to/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/var/lib/caddy \
  oaklight/caddy:v2.11.9-huaweicloud-cache-s3-alpine

⁠Server-side cache

{
    cache {
        ttl 1h
        stale 24h
        default_cache_control public, max-age=3600
    }
}

example.com {
    cache
    reverse_proxy localhost:8080
}

⁠Shared certificate storage on S3

Any S3-compatible backend works: AWS S3, MinIO, Oracle Cloud Object Storage. Several Caddy instances can share one bucket. The plugin takes a distributed lock, so only one instance issues a given certificate.

{
    storage s3 {
        endpoint "https://<endpoint>"
        bucket "caddy-certs"
        region "<region>"
        access_key "<access-key>"
        secret_key "<secret-key>"
        prefix "caddy"
        encryption_key "<32-byte-key>"
        use_path_style true
    }
}

Set use_path_style true for custom endpoints. The plugin comes from techknowlogick/certmagic-s3⁠.

⁠Build

⁠CI

.github/workflows/build.yml runs daily, on manual dispatch and on changes to the build files. It does this:

  1. Resolves the latest Caddy release, or the version given to the workflow.
  2. Expands the variant list into a matrix of variant × target.
  3. Skips any tag that already exists on Docker Hub.
  4. Builds linux/amd64 and linux/arm64 and pushes.
  5. Verifies every variant before the run passes:
    • caddy version reports the expected upstream version.
    • caddy list-modules --packages contains every expected plugin.
    • The config validates with caddy validate.
    • The container serves a request on :8080.
    • The runtime image runs as uid 1000.

Manual run with a pinned version and no push:

gh workflow run build.yml -f caddy_version=2.11.9 -f push=false
gh workflow run build.yml -f caddy_version=2.11.9 -f update_latest=true

Required repository secrets: DOCKERHUB_USERNAME and DOCKERHUB_TOKEN.

⁠Local
make build                                   # default variant, latest Caddy
make build VARIANT=full CADDY_VERSION=2.11.9
make version                                 # print the resolved image tag

⁠Plugin version pins

caddy-dns/dnspod tagged releases (through v0.0.4) still depend on libdns v0.2 and do not compile against libdns v1, which Caddy 2.11 requires. The build pins the commit that migrated to libdns v1 until a new tag is published. Override it when that changes:

docker build --build-arg DNSPOD_VERSION=v0.1.0 --build-arg WITH_DNSPOD=true .

Verified locally with Caddy 2.11.9: the default and full variants build, report the expected version, load every expected plugin, validate a config and serve a request.

⁠Optional libdns replacement

LIBDNS_HUAWEICLOUD_FORK replaces github.com/libdns/huaweicloud at build time with xcaddy --replace. Use it to test an upstream fix before it is merged.

docker build --target runtime \
  --build-arg WITH_HUAWEICLOUD=true \
  --build-arg LIBDNS_HUAWEICLOUD_FORK=github.com/<owner>/<repo>@<commit> \
  -t caddy:test .

Tag summary

Content type

Image

Digest

sha256:66334b243…

Size

25.2 MB

Last updated

2 days ago

docker pull oaklight/caddy:v2.11.9-full-alpine