Kamal uses Traefik as the default load balancer. Traefik comes with a default dashboard that is disabled by default. With the help of the dashboard, you can check your current active routes, enabled services and middlewares, and more.

What is Kamal?

Kamal is a tool for deploying Rails applications. It is based on Docker. It is the new way to deploy Rails 7.1+ apps.

What is Traefik?

Traefik is a load balancer and a router that runs in a Docker container. It serves as a reverse proxy. Think of it as an NGINX replacement.

What is the Traefik dashboard?

The Traefik dashboard provides insights into your running Traefik instance.

It contacts the Traefik API to retrieve information about it.

It shows your app’s running routes, services, entrypoints, features, and more.

How to enable the Traefik dashboard

The official Kamal docs provide an example of how you can enable the dashboard, but they are not complete, and they don’t make it obvious that the presented YAML configures the Traefik dashboard. They also don’t go into details about what the dashboard is.

When I was new to Kamal (I started using it back when it was called MRSK), I had no idea what Traefik was, and I discovered that it had a dashboard by pure accident.

To setup the Traefik dashboard, all you need to do is configure your config/deploy.yml, the default configuration file for Kamal.

You want to find the traefik: label, uncomment it, and add the following:

traefik:
  args:
    api: true
  labels:
    traefik.http.routers.dashboard.rule: Host(`traefik.example.com`)
    traefik.http.routers.dashboard.service: api@internal
    traefik.http.routers.dashboard.middlewares: auth
    traefik.http.middlewares.auth.basicauth.users: admin:$apr1$Jeizsy9/$KODzNFPDnNLdKSeXqupWI.


Let’s break it down:

  • traefik.args.api=true passes the --api flag to the Traefik CLI. It enables the API and the dashboard
  • traefik.http.routers.dashboard.rule tells the Traefik router where the dashboard should run. In this case, I created a subdomain and pointed Traefik to it. It doesn’t have to be a subdomain. If you want it to be accessible through a path, just use a PathPrefix, or consult the docs for advanced rules
  • traefik.http.routers.dashboard.middlewares attaches the auth middleware to the router so that the dashboard is protected from insecure access

  • traefik.http.middlewares.auth.basicauth.users sets the credentials for password access. The password is a hash that gets generated by the htpasswd command

    This is how you can generate your password. It is safe to commit it.

    htpasswd -nb admin password
admin:$apr1$Jeizsy9/$KODzNFPDnNLdKSeXqupWI.

    I like to keep this information in my Rails credentials so that I can always find it later.

    Run:

    rails credentials:edit

    Add your credentials:

    # Used to sign into the Traefik dashboard.
traefik:
  username: admin
  password: password

    Your Rails app doesn’t care about that, it’s just a reminder for you.

Finally, reboot your Traefik container:

kamal traefik reboot

Now, the dashboard should be live at https://traefik.example.com!

Sign in using your credentials, and you’re done.

You can discuss this article on X/Twitter:
https://twitter.com/kyrylosilin/status/1749375421370466344

Share on: