qmcgaw/caddy-scratch repository overview

⁠Caddy Scratch Docker

Caddy server v2.4.1 / v1.0.5 without root, without OS and with optional Caddy plugins

⁠Features

• Scratch⁠ based, so less attack surface and tiny
• Runs without root
• Plugins⁠

Size: uncompressed amd64 built Docker image

⁠Setup

✈️ Migrating from v1.0.x? ➡️ Wiki: Migrating⁠

⚠️ The following applies to the :latest tag. For other Docker tags, refer to the Wiki⁠

docker run -d --name caddy -p 80:8080/tcp -p 443:8443/tcp qmcgaw/caddy-scratch

or use docker-compose.yml⁠ with:

docker-compose up -d

The data is persistent in a Docker anonymous volume by default.

⁠Caddyfile

By default, this runs using the repository Caddyfile⁠. You could work you way out modifying the Caddy configuration using the Caddy API⁠. Otherwise, if you want to use a Caddyfile, follow these steps.

1. Create the directory: mkdir caddydir

2. Create a Caddyfile⁠ with the content you would like, in caddydir/Caddyfile. Note that at the top of your Caddyfile, there should be at least the following global block:

   {
       http_port 8080
       https_port 8443
   }
   

   Copy

3. Change the ownership and permission to match the Docker container

   chown -R 1000 caddydir
   chmod -R 700 caddydir
   

   Copy

   If you are on Windows, you may skip this step.

   Alternatively, you can run the container with --user="1001" for example, or as root with --user="root" (unadvised).

4. Assuming your current file path is /yourpath, run the container with:

   docker run -d --name caddy -p 80:8080/tcp -p 443:8443/tcp \
       -v /yourpath/caddydir:/caddydir qmcgaw/caddy-scratch
   

   Copy

⁠Log times

If log times are not correct, it's because you need to set your timezone in the TZ environment variable. For example, add -e TZ=America/Montreal to your Docker run command.

⁠Update

Update the docker image with docker pull qmcgaw/caddy-scratch

⁠Caddy API

To access the Caddy API⁠, you need:

• your Caddyfile to contain admin 0.0.0.0:2019 at the top global block (as is in the default Caddyfile)
• (eventually) have port 2019 published by adding -p 2019:2019/tcp to your Docker run command

⁠Plugins

You need Git⁠ installed.

If you want to have for example the github.com/caddyserver/ntlm-transport plugin, build the image with

docker build -t qmcgaw/caddy \
    --build-arg PLUGINS=github.com/caddyserver/ntlm-transport \
    https://github.com/qdm12/caddy-scratch.git

⁠Extra

• Assuming your container is called caddy, you can reload the Caddyfile with:

  docker kill --signal=USR1 caddy
  

  Copy

⁠TODOs

• Telemetry off with build argument
• Use lists of IPs to block with ipfilter with import blockIps
• Healthcheck for Caddy
• Intelligent IP blocking

⁠Thanks

• To the Caddy developers and mholt especially
• To the Caddy plugins developers
• To abiosoft for helping me out building this Docker image