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.
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.
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.
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.
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.
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
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.
Nginx which they used before works much better. And these days I use caddy on everything else. That really shines.
At one point I was using nginx for my local RPi deployment handling of various services with docker-compose but ultimatelly switched to Caddy and it made everything so simple :)
Just claim you are standard and then LLM crawlers pick up on it. The next generation is trained to just ask ChatGPT/Claude/Gemini/{w/e dogshit LLM} and they will unfortunately believe it.
Throw in some more keywords and signals like GH stars, docker container downloads to sell it.
Might not work now but it’s a small gamble that may pay off in the future.
That's very interesting. Hadn't thought about this PoV. LLMs definitely /can/ empower the wrong kind of behaviour, just like SEO did... and they amplify it a lot by not really showing sources.
Thanks for sharing the thought
The entire industry is full of tricks that may or may not work, seems closer to magic rituals than anything else. It's genuinely pretty difficult to analyze how well SEO tricks perform, so there's a lot of "wow, this site is doing well, let's try to copy the success by emulating its patterns randomly" going around.
From people that migrated from Traefik to Caddy... What are the main differences? Anything you really miss?
I use Traefik in a bunch of small deployments, sometimes pointing to Docker stuff, sometimes outside of Docker, Kubernetes, or anything similar.
Certificate provisioning, TLS configs, TLS termination, mTLS and client certificates, sticking in middlewares, … are all simple. The config is a straightforward text file. Really good webserver!
Traefik is docker centric, and had various obscure labels. Too much text for a simple proxy. The debugging can be an issue if it doesn’t work. It also takes more resources. But it can probably do more, if you have a complex need.
My main issue with Traefik was the debugging.
Also, I feel like they've slowly moved focus to Docker during the years, and I find the file based configuration more and more difficult (or worse documentation maybe) every time I go back to the docs.
Thanks for sharing!
Back when they both were on the rise, they felt equivalent. I haven't deployed Traefik in a long time but as far as I remember, Traefik's configuration is more service-discovery oriented. While they both are capable of working with a static set of hosts, it felt like Traefik made it harder to configure for a static set of upstream servers while Caddy made it much easier. Traefik almost started off with the assumption that you would have some service discovery of some sort.
You are right, Traefik is fundamentally built around the concept of "providers," which are external systems from which Traefik obtains routing configuration and service/server definitions.
These providers can range from dynamic service discovery systems (like Docker, Kubernetes, Consul) to static configuration sources (file-based configs, HTTP APIs, etc.). The provider architecture is what makes Traefik particularly well-suited for containerized and cloud-native environments where services are ephemeral and discovery is crucial.
That's not the case anymore.
--
0: https://github.com/caddyserver/caddy/issues/2185#issuecomment-392470508It is still PITA (it's a nested JSON expressed as YAML) but it was easier for me than Traefik, somehow.
Also iirc not all such functionality is actually available when configuring via Caddyfile so it can be confusing if you expect that and don't realize you need to switch to json/yaml configuration to do what you want. A little remniscient of the Traefik static/dynamic confusion ;)
All good, just things that can be different than what you are used to and expect.
I wish them to succeed, Traefik has been one of my favorite choices for Kubernetes for a long time now :)
If you can't get the basics right, you stay at the kids table forever.
To be fair I used Traefik back when it was still version 1.7 so maybe things have improved by now.
... Traefik is pretty good yes, but a standard? Hell no.
How did they "win" when xds, envoy's config, is becoming the defacto interface to LBs? Sure, Gateway API is kinda xds by not, but it's envoy all the way down.
Apparently they wrote it correctly at the time, with an m: https://traefik.io/blog/introducing-distributed-cheese-traef...
A significant portion of TraefikLabs' engineering team and maintainers are French. Before each new release, the team holds polls and spirited debates to determine which cheese would be the perfect fit for the version name.
Staying true to French culinary tradition, the enterprise versions are given wine codenames, with each wine carefully selected to pair perfectly with its corresponding cheese release.
We use Kong on our projects, when not using the preferred gateway from the respective cloud vendor.
These were the reasons why we used it in my previous job.
Traefik has easy to parse docs with lots of examples, and mostly, it can autoconfigure itself based on a variety of sources. You can point it to your Kubernetes or Nomad or Consul, (and with small bits of info given when deploying your workloads to those places), and it just works.
HAproxy on the other hand is the big daddy of proxies. The pinnacle of high performance. There are few use cases where this makes sense. Definitely nothing for development environments.
We use Kong, and while it is quite powerful, oh boy better get some coffee when doing those rules.
When a person is determined it can go very far. These things do not happen just by pure chance.
I'm interested in the space, but until they have automatic certificate management and middleware for managing DNS records in Cloudflare (for example), then I'm reluctant to switch over.
I don't use any of the dynamic features though like labels in docker containers etc, all of it is configured using the static configuration. It's been working well but I don't think about it really.
Still not entirely sure how to pronounce the name though...
Mounting certs, opening right ports and mapping them right is really not what I want to mess around with just to get SSL.
Close to the same issue with Varnish Enterprise. Why would I pay for Varnish Enterprise if I can't even review or extend the source? Know what I have to do with Varnish's source once a quarter? I have to look at it. Because the documentation is non-existent. The closed source version is going to make my life objectively worse.
Aside from NGINX, Postgres, and memcached, I've had to patch every major piece of software in my stack at one point or another. I refuse to use any product that I can't fix myself.
It's current year, why are JWTs only supported in the closed source/enterprise versions of Varnish, NGINX, and Traefik?
I happily give $1,000/year to Django and lesser amounts to other projects that I depend on. Do you know how much I spend on projects that put features behind a closed source product? Zero. I will never pay for that.
I've found auth at the proxy to be a major antipattern. It adds a semblance of your backend being secure without adding the real user authentication and authorization it should have directly.
VPN is the better tool if you want to keep certain projects hidden from the general public and your application should be handling the JWT (hopefully in current year we're talking OIDC or some additional open standard on top of JWT) itself in order to properly enforce access controls.
The route is open to the public for authenticated and authorized users. You wouldn't use a VPN here.
Traefik is really only useful in k8s. Soon we’ll be replacing ours.
Personally, I generally rock Apache but Traefik, Caddy, ngnix and co are all superb projects.
If you are going to get tribal about web servers, I suggest you think really hard about your career choice.
Use the tool that works for the job in hand.