Skip to main content

Install in Traefik with plugin

Tianji provides a Traefik plugin that allows you to easily integrate Tianji website analytics functionality into your Traefik proxy.

Plugin Overview​

traefik-tianji-plugin is a Traefik middleware plugin specifically developed for Tianji that can automatically inject the Tianji tracking script into your website without modifying your website code to start collecting visitor data.

Installing the Plugin​

1. Add Plugin in Static Configuration​

First, you need to add the plugin reference in Traefik's static configuration. The plugin version number references the git tag.

YAML Configuration​

Add the following to your traefik.yml or static configuration file:

experimental:
  plugins:
    traefik-tianji-plugin:
      moduleName: "github.com/msgbyte/traefik-tianji-plugin"
      version: "v0.2.1"

TOML Configuration​

[experimental.plugins.traefik-tianji-plugin]
  moduleName = "github.com/msgbyte/traefik-tianji-plugin"
  version = "v0.2.1"

Command Line​

--experimental.plugins.traefik-tianji-plugin.modulename=github.com/msgbyte/traefik-tianji-plugin
--experimental.plugins.traefik-tianji-plugin.version=v0.2.1

2. Configure Middleware​

After installing the plugin, you need to configure the middleware in the dynamic configuration.

YAML Dynamic Configuration​

In your config.yml or dynamic configuration file:

http:
  middlewares:
    my-tianji-middleware:
      plugin:
        traefik-tianji-plugin:
          tianjiHost: "https://tianji.your-domain.com"
          websiteId: "your-website-id"

TOML Dynamic Configuration​

[http.middlewares.my-tianji-middleware.plugin.traefik-tianji-plugin]
  tianjiHost = "https://tianji.your-domain.com"
  websiteId = "your-website-id"

Docker Compose Labels​

version: '3.7'
services:
  my-app:
    image: nginx:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-app.rule=Host(`my-app.local`)"
      - "traefik.http.routers.my-app.middlewares=my-tianji-middleware"
      - "traefik.http.middlewares.my-tianji-middleware.plugin.traefik-tianji-plugin.tianjiHost=https://tianji.your-domain.com"
      - "traefik.http.middlewares.my-tianji-middleware.plugin.traefik-tianji-plugin.websiteId=your-website-id"

Configuration Parameters​

Required Parameters​

  • tianjiHost: The complete URL of your Tianji server

    • Example: https://tianji.your-domain.com
    • If using the official hosted service: https://app.tianji.dev

  • websiteId: The website ID created in Tianji

    • Can be found in the website settings of your Tianji admin panel

Optional Parameters​

The plugin also supports other configuration parameters to customize behavior. For specific parameters, please refer to the GitHub repository documentation.

Using the Middleware​

After configuration, you need to use this middleware in your router:

YAML Configuration​

http:
  routers:
    my-app:
      rule: "Host(`my-app.local`)"
      middlewares:
        - "my-tianji-middleware"
      service: "my-app-service"

Docker Compose Labels​

labels:
  - "traefik.http.routers.my-app.middlewares=my-tianji-middleware"

How It Works​

  1. When requests pass through the Traefik proxy, the plugin checks the response content
  2. If the response is HTML content, the plugin automatically injects the Tianji tracking script
  3. The script starts collecting visitor data and sends it to the Tianji server when the page loads

Important Notes​

  • Ensure that the Tianji server address is accessible from client browsers
  • The website ID must be valid, otherwise data cannot be collected properly
  • The plugin only takes effect when the response content type is HTML
  • It's recommended to use the latest version of the plugin for optimal performance and features

Reference​