Integrating Coolify into an existing Traefik setup
Like many developers, I have side projects. But then, at one point, I want to host my side projects
Luckily, one of my side projects is maintaining a home lab for hosting small apps and tinkering. I have everything set up to expose service online and run any kind of container, but deploying requires a CD to build and push docker images to a registry. I also have to create a
docker-compose.yml file, ssh into my server every time I want to update an app. Plus, write the
Dockerfile for the app !
In the end, it adds a lot of friction to deploy a personal project online, even if it’s only for me…
Here is a lovely quote that represents the goal of Coolify :
An open-source & self-hostable Heroku / Netlify alternative
If you don’t know what Heroku and/or Netlify are, the main idea is that they provide CI and CD for your apps, building them and deploying them automatically every time there is new code pushed to the main branch. The most significant difference here is that it runs on your own infrastructure ! That can be a raspberry pi, a small VM somewhere, a VPS on a cloud provider, or an old computer you turned into a server !
To deploy a Coolify server, they provide you a script that will install everything (including docker and docker-compose) so that you can take a fresh installation of Linux, run the script, and you are live
Then you can connect any GitHub account with it, select a repo, and then you will be provided with a list of templates to set up your app with build-in support !
With that, you have a list of excellent features out of the box :
- Automatic build on push
- Automatic PR preview deploys
- Secret management
- Secret management for PR preview deploy
- Access to application live logs
- Same for builds logs
- Persistent storage for your app
Coolify is now integrating into the local docker engine and can expose service online on the fly, in the future, they are planing more integration point (like Kubernetes)
Traefik is an open-source Edge Router that makes publishing your services a fun and easy experience. It receives requests on behalf of your system and finds out which components are responsible for handling them.
Traefik has a system called , where a provider can provide all or part of the config. Here are some provider examples: a Kubernetes orchestrator, a Docker container (based on labels), a file one, and HTTP pooling. Traefik can use any of them to provide the configuration and mix them together.
If you run only Docker containers without any Kubernetes or any other orchestrator, the recommended way is to use labels. Using labels placed on a container, you can set all the configs for a specific container, but there is one issue : if you want to update the config, for example, change the domain, you would need to recreate the container with the new labels.
That’s where the HTTP provider comes in. Traefik will get an URL every x seconds to get the new config, so you can, thanks to that, have it switch on and off stuff on the fly ! And that is what Coolify uses since the .
And so, this way, Coolify can expose any apps it deploys in the same docker network as Traefik in seconds, without having to restart them. Here is a small graph to recap all of this :
In my home server, I already have 30+ services running on it with my current Traefik config. They all have their own middlewares, settings, and so on. So I was left with two options :
- Take a second domain name only for coolify and redirect from my first traefik to the second one
- Find a way to integrate coolify with my existing Traefik config
I decided to go for the second option because it’s less maintenance and more flexible.
Since Coolify now uses the HTTP provider of Traefik, that gave me an idea. What if I made a “man in the middle” Http provider ? An HTTP server that I make would call Coolify’s Traefik endpoint, modify some stuff, then output it.
So I did that ! I went on and found the endpoint from coolify, and explore what is included and what I wanted to keep and modify.
- Coolify export itself in the Traefik config, however, I already have exposed in my existing Traefik config, so I don’t need that
- The config provides
www.*routes. However, I don’t need that since I have a redirect from
- I don’t use the same names for my entrypoint, so I needed to change them (eg
httpson my config)
- I wanted to add a middleware to all routes
- I wanted to remove all
httproutes since I already have a redirect from
httpson every endpoint
So I decided to make a mapper that could modify some, all or none of thoes things. It’s a container that runs on the same network as coolify, and you can find it . Every customization is up to you and tailored to your needs !
I then run the container in its
docker-compose.yml file, and voilà, I have an output that matches my needs ! You also could deploy the container as a coolify service, but I decided to have it on the side in case I need more flexibility.
Now that I have a config that matches my current setup, I would still need to wire everything together !
I have a network called
web to expose containers from Traefik, and Coolify creates the
coolify-infra network to run it’s services on it. So I had to add the
coolify-infra networks to my Traefik instance so that it could reach Coolify’s services.
Next, I had to deactivate Traefik from Coolify itself so that there isn’t two Traefik running on the same server.
So, in the end, this is what I have :
I have , an entire local SSO system that integrates very well with Traefik (I worked with the folks on a on that if you want to know more). This allows me to have all my services behind a single auth system with custom roles and rules based on the URL. I can even say that all routes are private by default and requires double factor auth and specify some specifics URL that I want to be public. I wanted to do this with Coolify so that future apps can be secured, reducing the attack surface (in other words, I can put hacky code without too much risk).
Also another thing I wanted is to use the same domain and server to simplify its networking management and maintenance. I run all of this in my home lab, and even tho I could have two Traefik, with one forwarding to the other one another domain, I didn’t want this added complexity that could be introduced by running a duplicate system.
Lastly, I wanted to reuse my . This was already done in my current Traefik and avoids spamming Let’s Encrypt certificate and get (this already happened once to me, and a week can feel really long to be able to get new certificates).
So, in the end, my whole setup looks like that :
Well, if you have anything I talked about before, that may be interesting to you! But there are also some other use cases I didn’t talk about.
Here are some examples that might be useful :
- to protect your services
- to automatically gzip every request that is bigger than 1024 bytes (by default, but can be configured to whatever you want)
- is not as secure as an SSO setup like Authelia, but it can be a first line of defense!
- to have custom errors pages across multiple services
- multiple middlewares together !
So let’s recap, what are the Pro and Con of running your own Traefik with Coolify :
- Integrating into an existing Traefik instance
- Being able to use wildcard SSL certificates
- Being able to use your own SSO (like Authelia) in front of all your apps
- Being able to add any middlewares on top of it
- Bring your own config
- Non-standard use of Coolify
- Might break if Coolify changes the endpoint or names in their Traefik output
- You will have to maintain your own Traefik instead of relying on Coolify to do it