Traefik + Oauth2 Proxy + Zitadel + Homarr

A zero-click integration with Pulumi

Goal ♻️

The goal is to provide the following integration, without the hassle for clicks, thus providing high grade of replicability:

Disclaimer ⚠️

This project makes use of self signed certificates (with relative insecure flags here and there) and is far from being (and pretending to be) a complete solution for all use cases.

It is also far from being a piece of art. Still, I though it was good enought to be shared and to spread some insight on an integration hard to find examples on.

Last but not least, depending on your system some adjustment may be required, but I hopw you understand the topic enough for testing it and adjust to your needs (or maybe open a pull request 👻).

I also decided to use emoji in this README, simply because.

Zitadel 🔑

For this to work, Zitadel is configured with the following setup:

Architecture 💡

Behind the scenes 📜

Everything started with plain k8s manifest files. This led to manifest jungle and little to be parametrized. Also, because on dependencies between services, setting up the node was painfully slow due to all of the CrashLoopbackOff waiting time.

I then moved to a monolithic Pulumi project. It was better, still I had a huge configuration file and not optimal information exchange between resources.

Present 💻

I decided to move to a micro-stack Pulumi architecture. This way I have smaller config files and less issues on information exchange between stacks. Everything is orchestrated with Pulumi Automation API.

Requirements 🛂

Host requirements

Use of Pulumi local-commands results in the following tools requirements on the host machine (because I wrote local command scripts in bash 😈):

• curl
• jq
• openssl

Target requirements

Depending on your final setup, changes to your hosts file may be required:

127.0.0.1 homelab.local
127.0.0.1 zitadel.homelab.local
127.0.0.1 whoami.homelab.local
127.0.0.1 oauth2-proxy.homelab.local
127.0.0.1 traefik.homelab.local

Parametrization 😵‍💫

Pretty much everything have been parametrized in config.yaml.

However, Zitadel domain is hardcoded in commons/scripts/functions.sh and data/remote/homarr/config/default.json too.

Setup 🔧

python -m venv ./venv
source venv/bin/activate
pip install -r requirements.txt

You will also have to change mount point for Homarr and Postgres:

• src/micro-stacks/homarr/Pulumi.yaml:

volume:
    config: 
        mountPath: /app/data/configs
        path: "PATH_TO(data/remote/homarr/config)_OR_WHATEVER"
        storage: 1Gi

• src/micro-stacks/postgres/Pulumi.yaml:

volume:
    data: 
        mountPath: /var/lib/postgresql/data
        path: "PATH_TO_WHEREVER_YOU_WANT_POSTGRES_DATA_TO_BE_MOUNTED"
        storage: 1Gi

Run 🆙

Within virtual env:

PULUMI_CONFIG_PASSPHRASE="YOUR_PASSPHRASE" python3 main.py

Then navigate to https://homelab.local.

First login:

User: admin@homelab.local
Password: Password1!

Destroy 🆓

Within virtual env:

PULUMI_CONFIG_PASSPHRASE="YOUR_PASSPHRASE" python3 main.py destroy

TODOs ☑️

Far from being perfect, I would like yet to:

• Inspect on _sync_await possible alternatives
• Proper secret handling (please, don't say a word, I also have a life and couldn't cover everything in one single run 🙃)
• Double check on duplicated configurations (highly possible)
• Fine tune k8s requests and limits parameters

Inconsistencies 🤔

Homarr has the possibility to add and invite users, but with oidc provider only this is a bit inconsistent. Discussion here: ajnart/homarr#2251

Hacks 🔞

In order to skip admin account for basic auth in Homarr, a VERCEL variable should be passed to the container. Discussion here: ajnart/homarr#2251

Links 🌐

Traefik: https://traefik.io/traefik/
Oauth2 Proxy: https://oauth2-proxy.github.io/oauth2-proxy/
Zitadel: https://zitadel.com/
Homarr: https://homarr.dev/
Pulumi: https://www.pulumi.com/

Dashboard background 🌅

https://unsplash.com/it/@lukechesser

Thanks to 🙏

https://github.com/tgragnato, last time he asked me "Why not Pulumi?". This project seemed a good fit.