[gethly]

I use Traefik for local development on daily basis, where I have to run double digit https services. It works, but it was a pain to set up. The documentation sucks ** and the config is confusing AF. I would never recommend this to anyone. If i will have to reinstall my computer one day, Traefik will not be welcomed back.

[jspdown]

Traefik maintainer here.

Documentation quality has been a common complaint. Previously, we only provided reference documentation and relied on the community to create tutorials and guides.

Based on feedback like yours, we've completed documentation rewrite. Have you had a chance to review the new version? Your feedback is taken very seriously, so we'd greatly value your thoughts on these improvements.

[gethly]

I am unable to give you feedback as I have no need to use the documentation at this time and going over it without having a need to find something would be pointless. And I have set up my local Traefik instance quite some time ago, so I do not remember my struggles back then.

[crockeo]

We recently just deployed Traefik at $job, and found it pretty easy! I didn't do the work myself, but I directly managed the engineer deploying it. It was predominantly reference material but that was really all we needed to get it set up.

[dolni]

Hi there. I'm a brand new Traefik user. It's bundled with k3s, so I set it up for my homelab on a single node cluster. I'm a technology professional who has worked in infrastructure and software roles for more than 15 years.

I appreciate that you revised the docs, but I still found it quite difficult just to get started. My experience was poor enough that I almost switched to Caddy. The thing that kept me from doing that is that Caddy requires a custom container build for DNS-01 ACME challenges which I didn't particularly want to deal with. I found Caddy's documentation much easier to grapple with, so that could serve as some inspiration.

I have some feedback I'd offer of my own, too:

1. I'd recommend you take a look at the Divio documentation system: https://docs.divio.com/documentation-system/. Your documentation aligns to this vaguely, but I'd recommend reading about the different doc types and applying that feedback throughout the docs.

2. Traefik's tutorial and how-to docs are very dense and feel overwhelming. [1] Related to my first point, I think you're trying to provide too much information in the wrong places. Tutorials and how-to guides should be very focused and limit explanation to only that which is absolutely necessary.

3. Reference and understanding docs are mixed together. I'd recommend using an approach more like Caddy's, where the config reference (https://caddyserver.com/docs/json/) shows prominently what the expected config schema is, and all of the fields are explained briefly. If there is very nuanced behavior for a particular option, consider moving that to a separate reference or explanation page.

4. Having a few How-To guides for the most common patterns which include complete configurations would be helpful.

[1] Here are some concrete examples:

- On https://doc.traefik.io/traefik/setup/kubernetes/, there is a whole introductory session about setting up Kubernetes and I have to scroll before reading anything related to Traefik. It's not only unnecessary -- it's noise. Nobody is going to consult Traefik's docs for setting up Kubernetes, so just omit it.

- https://doc.traefik.io/traefik/setup/kubernetes/ and https://doc.traefik.io/traefik/getting-started/kubernetes/ are different pages which seem to explain mostly the same things. They both include too much irrelevant information, like overly explaining what Helm commands do. Similar to the previous point, it is not the job of Traefik's documentation to explain Helm to me.

[jspdown]

Thanks for the detailed feedback. This is exactly the kind of input we need.

We're going to work through these points with the team. Appreciate you sticking with Traefik despite the documentation friction.

[dolni]

Thanks for building a cool piece of software!

Traefik really is awesome once you can get your head wrapped around the configuration.

[pbronez]

Excellent feedback! This is valuable advice for any project.

[eurekin]

Oh, the static/dynamic split is brutal (and I believe some options have been moved around)...

Once you referenced routers, middleware and services simply by name, but that changed into per-source scoped versions (e.g. service1@file, middleware@docker).

I kept bumping into those edge cases (custom SSL cert set-up was really confusing), but thanks to chatgpt, I at least ended up with workable solutions.

[frogperson]

OMG yes. I want to like Traefik, but the thought having to set it up again is not something i look forward to. Why cant it just work out of the box?

Caddy is probably my new favorite. It works out of the box, its super low resource, handles a ton of traffic, and the docs are decent.

[LtdJorge]

I really like how it can be easily configured from Docker labels (from Portainer for example), or from your big production Consul cluster alike. But yeah, the docs need a lot of work, it’s difficult to figure out the format many times, it lacks examples, and things that need to be enabled together have their docs at different places.

[baby_souffle]

Your point about having to enable two different things at the same time in two different places is a concise way of expressing my extreme frustration with that project.

I burned the better part of a Saturday trying to figure out why a relatively straightforward configuration wasn't applying and it's because one half of the configuration that I was trying to apply has to be done in the static manner and not the dynamic manner.

Documentation doesn't really spell this out and after quite a bit of frustrated googling I found a few other people complaining about effectively the same problem. It's only a few lines of code to spit out something along the lines of "hey, you're trying to configure ¢thing in an inappropriate way. Did you mean to configure ¢thing over in €thisLocation?" message... But nope, that would make things so much simpler and easier to use and probably cut into their support contract sales...

Now I basically just stick with nginx because it's documentation isn't crap, useful and applicable examples are all over the Internet.

[mkesper]

Sticking to nginx seems not to be an option for many as at least ingress-nginx will not be get any new features anymore (as mentioned in the article).

[baby_souffle]

> Sticking to nginx seems not to be an option for many as at least ingress-nginx will not be get any new features anymore (as mentioned in the article).

For k8s, yeah. It should still be a useful tool for other things? Or did i miss a memo about nginx being EOLd?

[skibbityboop]

Yeah, kinda have to agree. I like traefik fine but getting mTLS working with it was a serious pain and the docs for doing so were _terrible_, had to keep searching around and piecing together bits from various third party blogs. Coming from haproxy where the documentation is _so_ _much_ better and things like e.g. mTLS are vastly easier, it was not a fun experience but we did finally get traefik to work as we needed.

[Jnr]

I wonder how you are using it. I am mainly using Traefik with docker compose labels and it was not that hard to set up once you understand the concepts of routers, middlewares and services. I would use it for any homelab that has to host more than one service.

I also recently started playing around with web UI layer that generates traefik json config. Currently it is quite basic since it was initially made to provide limited time access to development instances but it could in theory manage most important aspects of proxy config and replace something like nginx-proxy-manager. https://github.com/Janhouse/traefik-proxy-admin

[trenchpilgrim]

I was once tasked with looking into using Traefik and yeah the documentation at the time was so bad I couldn't figure it out. Ended up using Envoy IIRC.

[tracker1]

I use caddy similarly, but it's a pretty straight forward setup.

[theSuda]

As a self-hosting noob, I never got traefik to work properly, then caddy just worked and has been working since.

[wkat4242]

Yeah same here. Caddy is so well designed. I hated traefik from the start and even though it works now I still hate it. The moment I used caddy everything was clear and just worked. Basically what nginx used to be 15 years earlier. But it didn't really keep up with the times and they care more about the commercial thing now.

[windexh8er]

I have the opposite opinion. Traefik documentation is good if you take the time to read and comprehend it - and it has gotten significantly better over the last few years, it being bad (e.g. "it sucks") is an old trope at this point. I don't use Caddy or nginx because of the first class routing and middleware capabilities of Traefik. I've got it deployed in dozens of services and it's so easy to use one you've solidified your boilerplate that everything else, to me, appears to be a pain now.

To each their own but it's interesting you find it useful (you use it) yet it won't be welcome back. Maybe, as others have noted, try it in Docker (or k3s/k8s/etc). Once the base configuration you want is configured and deployed all you need to do is place labels in for dynamic service configuration.

[wkat4242]

Yeah I deal with it because it's part of the ansible matrix playbook. But I hate it, I always have issues with it. Complex configs, things not quite working right.

Nginx which they used before works much better. And these days I use caddy on everything else. That really shines.

[taleodor]

I have completely opposite experience. To me Traefik is the easiest thing to work with on the market. It should be even easier now to setup using Agentic AI.