Sad, No clear Documentaion

[afzl-wtu]

It is really very sad that after spending one hour on this app and compiling my caddy with this app. I am still at no where. Whenever I try to copy code provided in README.md file for IMAP setup i get this:

docker exec caddy sh -c "cd /etc/caddy && caddy fmt --overwrite && caddy reload"
{"level":"info","ts":1728466368.791589,"msg":"using adjacent Caddyfile"}
Error: adapting config using caddyfile: Caddyfile:14: unrecognized directive: layer4

I do not know where to put your provided code:

layer4 {
        0.0.0.0:993 {
            route {
                tls
                proxy {
                    proxy_protocol v1
                    upstream localhost:143
                }
            }
        }
}

I want caddy to handle my caddy generated ssl certificate at port 993 for Imap and then proxy unencrypted connection to port 143

I want something like this in my caddyFile:

# my mail domain with caddy auto ssl
mail.mydomain.com:993 {
     reverse_proxy 127.0.0.1:143
}

But I am still at nowhere.

[afzl-wtu]

Finally I got it make work by placing

{
        layer4 {
                127.0.0.1:993 {
                        route {
                                tls
                                proxy {
                                        proxy_protocol v1
                                        upstream 127.0.0.1:143
                                }
                        }
                }
                127.0.0.1:465 {
                        route {
                                tls
                                proxy {
                                        proxy_protocol v1
                                        upstream 127.0.0.1:587
                                }
                        }
                }
        }
}

At top of my Caddyfile.
But I now have a question. any device that try to connect to my server, will it get an auto-generated letsencrypt ssl certificate for mail.mydomain.com or it will get self signed certificate. If it get self signed certificate is it a security risk or how to assign letsencrypt certificate?

[ArcCal]

If you like a particular plugin in Caddy, in addition to reading the documentation, it's a good idea to closely follow the discussions in the issues section. Many use cases and potential pitfalls are discussed there.

[ArcCal]

The documentation issues with Caddy plugins have been persistent for a long time, and the discussions in the issues section are an essential source of information or means of obtaining it.

[vnxme]

@afzl-wtu You are right it would be great to have more documentation for all the wonderful features this project has. As fairly mentioned by @ArcCal, issues and PRs are valuable sources of information here, in addition to the comments written in the code. Anyone may also help the project by composing extra docs, examples, etc.

But I now have a question. any device that try to connect to my server, will it get an auto-generated letsencrypt ssl certificate for mail.mydomain.com or it will get self signed certificate. If it get self signed certificate is it a security risk or how to assign letsencrypt certificate?

The answer to your question really depends on what you have in your config. The layer4 module doesn't generate any certificates itself. When tls handler is used, it tries to find the best available certificate for the requested domain name and, if found, terminates TLS. And the certificates are those generally available to/generated by Caddy.

You may influence certificate selection/generation by specifying TLS options inside a website block:

{
	layer4 {
		:993 {
			...
		}
		:465 {
			...
		}
	}
}

mail.mydomain.com {
	tls ...
}

[mholt]

Hi, I actually agree, the docs for this module could be greatly improved. I've simply been too busy to prioritize it myself.

Caddyfile support is a relatively new enhancement by the way.

I would gladly accept pull requests to improve the docs!

We could also potentially start a wiki if needed, maybe with examples, to keep the README tidy.