Skip to content

Connecting Projects

Any Docker-based project can be routed through claritools by joining the autoproxy network and adding Traefik labels to its container. Once connected, your service gets a clean HTTPS URL and appears on the Homepage dashboard automatically.

Generate a snippet

task add name=myapp port=3000

Or from any directory (after running task init):

task -g claritools:add name=myapp port=3000

Parameters

Variable Required Description
name Yes Service name — used in the URL and Traefik labels
port Yes The port your app listens on inside the container
group No Dashboard group on Homepage (default: Projects)

Example

Running task add name=myapp port=3000 produces:

networks:
  autoproxy:
    external: true

services:
  myapp:
    # ... your existing service config ...
    networks:
      - autoproxy
    labels:
      # Traefik routing
      traefik.enable: true
      traefik.http.routers.myapp.rule: "Host(`myapp.local.ciservers.net`)"
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls: true
      traefik.http.services.myapp.loadbalancer.server.port: 3000
      # Homepage dashboard discovery
      homepage.group: Projects
      homepage.name: myapp
      homepage.href: "https://myapp.local.ciservers.net"
      homepage.icon: mdi-application

Paste the relevant parts into your project's docker-compose.yml.

How it works

  1. The autoproxy network is an external Docker network created by claritools
  2. Your container joins this network alongside the Traefik container
  3. Traefik reads the labels from your container and creates a route
  4. Homepage reads the labels and adds the service to the dashboard
  5. Your service is accessible at https://<name>.local.ciservers.net
Your project (docker-compose.yml)         Claritools (docker-compose.yml)
  |                                         |
  | joins autoproxy network                 | Traefik reads labels
  +------ autoproxy Docker network ---------+
                                            |
                                            v
                                     https://myapp.local.ciservers.net

Requirements

  • Claritools must be running (task start)
  • Your container must be on the autoproxy network
  • Your container must have traefik.enable: true
  • The port label must match the port your app listens on inside the container

Authentication in dev mode

In dev mode, connected projects are not automatically protected by OIDC authentication. The ForwardAuth middleware is only applied to claritools' own services via explicit label overrides in docker-compose.dev.yml.

To protect your project with OIDC in dev mode, add the middleware labels to your service:

labels:
  traefik.http.routers.myapp.middlewares: oauth-errors@docker,oauth-auth@docker

Tips

  • Choose a short, unique name — it becomes the subdomain
  • Use the group parameter to organize services on the dashboard (e.g., group="Frontend")
  • You can customize the icon with homepage.icon — see the Homepage icon reference
  • Both claritools and your project must be running for the route to work