traefik-umami-plugin

Use Umami Analytics with the Traefik Reverse Proxy.

This plugin enables you to build a middleware to provide umami anytics to any web servive.

Pros:

• No need to modify the web service
• Harder to block by adblockers
• No need for JavaScript Fetching
• No need for JavaScript

Features

• Script Tag Injection - Inject the script.js as a script tag
• Script Source Injection - Inject the script.js as raw JS code
• Request Forwarding - Forward requests behind forwardingPath to th unami server
• Server Side Tracking - Trigger tracking event from the plugin, No JS needed.
• Injection when compressed - Issue, PR in progress

Installation

To add this plugin to traefik reference this repository as a plugin in the static config. The version references a git tag.

experimental:
  plugins:
    traefik-umami-plugin:
      moduleName: "github.com/1cedsoda/traefik-umami-plugin"
      version: "v1.0.2" 

[experimental.plugins.traefik-umami-plugin]
  moduleName = "github.com/1cedsoda/traefik-umami-plugin"
  version = "v1.0.2"

With the plugin installed, you can configure a middleware in a dynamic configuration such as a config.yml or docker labels. Inside traefik-umami-plugin the plugin can be configured.

Only umamiHost and websiteId options are required to get started. The middleware can then be used in a router. Remember to reference the correct provider namespace.

http:
  middlewares:
    my-umami-middleware:
      plugin:
        traefik-umami-plugin:
          umamiHost: "umami:3000"
          websiteId: "d4617504-241c-4797-8eab-5939b367b3ad"
          forwardPath: "umami"
          scriptInjection: true
          scriptInjectionMode: "tag"
          autoTrack: true
          doNotTrack: false
          cache: false
          domains:
            - "example.com"
          evadeGoogleTagManager: false
          serverSideTracking: false
          serverSideTrackingMode: "all"

[http.middlewares]
  [http.middlewares.umami.plugin.traefik-umami-plugin]
    umamiHost = "umami:3000"
    websiteId = "d4617504-241c-4797-8eab-5939b367b3ad"
    forwardPath = "umami"
    scriptInjection = true
    scriptInjectionMode = "tag"
    autoTrack = true
    doNotTrack = false
    cache = false
    domains = ["example.com"]
    evadeGoogleTagManager = false
    serverSideTracking = false

Configuration

Umami Server

key	default	type	description
umamiHost	-	string	Umami server host, reachable from within traefik (container). eg. umami:3000
websiteId	-	string	Website ID as configured in umami.

Request Forwarding

Request forwarding allows for the analytics related requests to be hosted on the same domain as the web service. This makes it harder to block by adblockers. Request forwarding is always enabled.

key	default	type	description
forwardPath	umami	string	Forwards requests with this URL prefix to the umamiHost

Requests with a matching URL are forwarded to the umamiHost. The path is preserved.

• <forwardPath>/script.js -> <umamiHost>/script.js
• <forwardPath>/api/send -> <umamiHost>/api/send

Script Injection

If scriptInjection is enabled (by default) and the response Content-Type is text/html, the plugin will inject the Umami script tag/source at the end of the response body.

The data-website-id will be set to the websiteId.

key	default	type	description
scriptInjection	true	bool	Injects the Umami script tag into the response
scriptInjectionMode	tag	string	tag or source. See below
autoTrack	true	bool	See original docs data-auto-track
doNotTrack	false	bool	See original docs data-do-not-track
cache	false	bool	See original docs data-cache
domains	[]	[]string	See original docs data-domains
evadeGoogleTagManager	false	bool	See original docs Google Tag Manager

There are two modes for script injection:

• tag: Injects the script tag with src="/<forwardPath>/script.js" into the response
• source: Downloads & injects the script source into the response

Server Side Tracking

The plugin can be configured to send tracking events to the Umami server as requests come in. This removes the need for JavaScript on the client side. It also allows to track pages that are not text/html or are not rendered by a browser.

However, it is not possible to track title or display values, as they are not available on the server side.

SST can be combined with script injection, but it is recommended to turn of autoTrack to avoid double tracking.

Tracked events have the name traefik.

The domains configuration is considered for SST as well. If domains is empty, all hosts are tracked, otherwise the host must be in the list. The port of the host is ignored.

key	default	type	description
serverSideTracking	false	bool	Enables server side tracking
serverSideTrackingMode	all	string	all or notinjected. See below

The mode notinjected is useful if you want to use SST and script injection at the same time, but want to avoid double tracking. Perfect for full analytics coverage of your web service. There are two modes for server side tracking:

• all: Tracks all requests
• notinjected: Tracks all requests that have not been injected (always if scriptInjection is disabled)