Integrating Coolify into an existing Traefik setup

June 30, 2022 ––– views Updated July 13, 2022

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…

So I started my quest for a tool that could help me lower the friction, and that is when I found Coolify, made by Andras Bacsai.

What is coolify

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 !

screenshot of coolify showing Node, static, php, laravel, docker, svelte, vuejs, nuxtjs, gastby, astro, eleventy, react, preact, nextjs, nestjs, rust, python and deno as predefined modules

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)

How Coolify exposes services online

Coolify, under the hood, uses Traefik to expose the services online. But what is Traefik ? Here is a quote from their website :

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 providers, 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 v2.9.0.

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 :

But I already have a Traefik running on my server

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.

Creating a mapping between Coolify and traefik

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 www.* to *
  • I don’t use the same names for my entrypoint, so I needed to change them (eg websecure is called https on my config)
  • I wanted to add a middleware to all routes
  • I wanted to remove all http routes since I already have a redirect from http to https on 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 here. 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.

Integrating the Coolify with Traefik

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 and coolify-infra network to run it’s services on it. So I had to add the coolify and 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 :

Why did I do all that ?

I have Authelia, an entire local SSO system that integrates very well with Traefik (I worked with the Ibracorp folks on a video 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 wildcard certificate. This was already done in my current Traefik and avoids spamming Let’s Encrypt certificate and get rate limited (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 :

Ok, that’s nice, but why would you do 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.

With this system, you can also do cool things like adding any Traefik middlewares.

Here are some examples that might be useful :

  • Rate limit to protect your services
  • Compress to automatically gzip every request that is bigger than 1024 bytes (by default, but can be configured to whatever you want)
  • Basic Auth is not as secure as an SSO setup like Authelia, but it can be a first line of defense!
  • Error pages to have custom errors pages across multiple services
  • Chain 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
Share this article on Twitter, and more!