Using Umami with Hugo

Umami is a self-hostable web analtics system similar to Google Analytics. From my point-of-view it has several advantages compared to Google Analytics:

• Data Ownership: it is self-hosted so the data is stored on my own server
• Privacy: Google Analytics uses cookies, so can be problematic to comply with certain privacy laws such as GDPR.
• Simplicity: I am a sysadmin, not a data scientist. Umami’s interface is very simple compared to Google Analytics. Granted, this is partly because it does less, but it is fine for me.

This site is hosted on Gitlab Pages and I run Umami on my K3s which has an ingress controller accessible from outside.

Deploying Umami

To host Umami you need a DB which can be either MariaDB or PostgreSQL. I do not really care which, but I have been pretty busy with Immich recently which use PostgreSQL. As a result that is fresh in my mind so I use that. It may not be the best way to decide, but it is good enough for me.

I deployed using FluxCD and you get the code here. PostgreSQL is managed by CloudNative-PG using db.yaml:

---
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: umami-postgres
spec:
  instances: 1
  imageName: ghcr.io/cloudnative-pg/postgresql:17.2
  storage:
    size: 5Gi
    storageClass: longhorn

  monitoring:
    enablePodMonitor: true # Enable the PodMonitor for Prometheus
    tls:
      enabled: false # Set to true if TLS is enabled for metrics

That creates my DB node (or cluster) along with a secret that I can reference with the credentials.

I did not bother looking for Helm chart, I simply created a Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: umami
  name: umami
  namespace: umami
spec:
  replicas: 1
  selector:
    matchLabels:
      app: umami
  template:
    metadata:
      labels:
        app: umami
    spec:
      containers:
      - image: ghcr.io/umami-software/umami:postgresql-latest
        name: umami
        env:
        - name: TZ
          value: Europe/Paris
        - name: DATABASE_TYPE
          value: postgresql-latest
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: umami-postgres-app
              key: uri
        - name: APP_SECRET
          valueFrom:
            secretKeyRef:
              name: umami-app-secret
              key: app-secret
        ports:
        - containerPort: 3000
          name: http
          protocol: TCP
        resources: {}
        livenessProbe:
          httpGet:
            path: /api/heartbeat
            port: http
          failureThreshold: 5
          initialDelaySeconds: 30
          periodSeconds: 30

There I reference the uri key in the secret the Operator created to create the variable DATABASE_URL. The only other thing in here is the APP_SECRET which needs to be a secret.

There is a few other things you will find in the repo, but that is the essentials.

You can now login and follow the instructions.

Integrate with Hugo

Once you have created the website, you need to put the script in the pages headers. I am using the Ananke theme which supports adding scripts to the page headers. All you do is create the file layouts/partials/head-additions.html and paste the contents that Umami gave you.

Commit, deploy and you should start getting some stats in Umami. Obviously, if you don’t you need to publish more to get more traffic.

• Stats
• Lab