Caddyfile file bind mount issues

[msladek]

The current documentation suggests mounting the Caddyfile as a file:

volumes:
  - $PWD/Caddyfile:/etc/caddy/Caddyfile

This approach can lead to issues due to how Docker handles file binds. When an individual file is mounted into a container, Docker mounts the inode of the file on the Linux filesystem. If the file is replaced (which many editors do), the inode changes. Thus it can happen that writes to the file after starting the container won't be reflected between the inside and outside of the container.
For more detailed information, refer to this Docker issue: moby/moby#6011

To avoid such issues, it is often suggested mount the parent directory instead of relying on single file bind mounts.

volumes:
  - $PWD/etc:/etc/caddy

with the file tree

├── compose.yml
└── etc
    └── Caddyfile

It would make sense update the documentation accordingly or at least incorporate a warning about this docker issue with file mounts.

[jordonedavidson]

The current documentation at https://hub.docker.com/_/caddy suggests putting the custom Caddyfile inside a conf directory that is mounted inside /etc/caddy/

To override the default Caddyfile⁠ , you can create one in the subfolder conf at $PWD/conf/Caddyfile and mount this folder at /etc/caddy:

$ docker run -d -p 80:80 \
    -v $PWD/conf:/etc/caddy \
    -v caddy_data:/data \
    caddy

⚠️ Do not mount the Caddyfile directly at /etc/caddy/Caddyfile

This should take care of the situation you describe.

[jordonedavidson]

It should be noted that you need to provide a new command to get caddy to use this Caddyfile in the container.

The service in a docker compose file might look like this:

version: "3.3"

services:
  proxy:
    image: caddy:2.8.4-alpine
    container_name: "web-proxy"
    restart: unless-stopped
    command: caddy run --config /etc/caddy/conf/Caddyfile --adapter caddyfile
    volumes:
      - $PWD/Caddyfile:/etc/caddy/conf/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    ports:
      - "80:80"
      - "443:443/tcp" 
      - "443:443/udp"
volumes:
  caddy_data:
  caddy_config:

[polarathene]

It should be noted that you need to provide a new command to get caddy to use this Caddyfile in the container.

1. Why are you following up with this comment with advice to perform a direct file mount for Caddyfile?
2. version: "3.3" is not required for any modern version of Docker Compose (v2 has been out for a while now).

---

You can mount the folder and no custom command is required (only if you want to use a different location):

# Image has only the Caddyfile at this location:
$ docker run --rm -it caddy:2.8 ls /etc/caddy
Caddyfile

# Check image ENTRYPOINT and CMD directives:
$ docker inspect caddy:2.8 | jq '.[0].Config | { entrypoint: .Entrypoint , cmd: .Cmd | join(" ") }'
{
  "entrypoint": null,
  "cmd": "caddy run --config /etc/caddy/Caddyfile --adapter caddyfile"
}

---

Direct file mount (valid, so long as you don't expect any changes while the container is running to be received):

services:
  reverse-proxy:
    image: caddy:2.8
    # File bind mount:
    volumes:
      - ./config/Caddyfile:/etc/caddy/Caddyfile:ro

Bind mount volume (better when you expect changes on the host to be in sync with the copy in the container):

services:
  reverse-proxy:
    image: caddy:2.8
    # Folder bind mount:
    volumes:
      - ./config:/etc/caddy:ro

NOTE:

• :ro only prevents writes from within the container.
• I've only focused on the Caddyfile above. I've omitted other relevant config like volumes you may want for persistence.

[msladek]

The current documentation at https://hub.docker.com/_/caddy suggests putting the custom Caddyfile inside a conf directory that is mounted inside /etc/caddy/

The documentation has been updated to that effect just recently without referencing this issue.

I'm therefore closing this issue as done.

[polarathene]

The documentation has been updated to that effect just recently without referencing this issue.

For reference, that is the commit by their CI running update.sh, the actual change to the Caddy DockerHub README was done here: docker-library/docs#2483

Ah I see you just referenced this issue from the associated one that PR mentions 😅