ENG | Setting Up Umami Analytics with Jekyll-Chirpy

I’ve spend few hours fighting with this easy task so you don’t have repeat my mistakes 🙂

Introduction

As a website owner or blogger, understanding your audience’s behavior and engagement metrics is crucial for making informed decisions about content strategy and site optimization. Traditional web analytics tools often raise privacy concerns due to their extensive data collection practices, including tracking user behavior across multiple websites through cookies and other methods.

Umami is a privacy-focused, open-source alternative to Google Analytics or Matomo that allows you to self-host your website analytics, giving you complete control over your data and respecting user privacy. Unlike traditional analytics platforms, Umami does not use cookies or track users across websites, making it compliant with privacy regulations such as GDPR without the need for obtrusive consent banners.

In this guide, we’ll walk through the steps to integrate Umami Analytics with Jekyll-Chirpy, enabling you to track and analyze website traffic while keeping your visitors’ data secure and respecting their privacy.

Prerequisites

• Jekyll-Chirpy v7.0.0 or higher: This version was released on May 11, 2024, Chirpy is a Jekyll theme with lot of extra features.
• Podman or Docker infrastructure: Basic knowledge of container management is necessary, as the installation involves container deployment.
• Cloudflare tunnel: A running Cloudflare tunnel is not essential, but makes HTTPS connection to your self-hosted websites easier and more secure.

You can search Archive for articles from May to July 2023, or articles with self-hosting tag to learn more.

Install Umami Analytics

Create a Docker Compose File

Create a new docker compose file and paste the following content as a starting point.

# Docker Compose file for Umami Analytics with PostgreSQL
# https://github.com/umami-software/umami/blob/master/docker-compose.yml
# https://github.com/umami-software/umami/pkgs/container/umami/212027417?tag=mysql-v2.11.3
# https://github.com/umami-software/umami/pkgs/container/umami

version: '3'
volumes:
  umami-postgresql-db:
services:
  # This config is specific to umami
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    container_name: umami
    ports:
      - "8083:3000"
    environment:
      DATABASE_URL: postgresql://umami:umami@umami-postgresql:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: ${UMAMI_SECRET}
    restart: unless-stopped
    env_file: /home/pavel/docker/.env
    depends_on:
      umami-postgresql:
        condition: service_healthy
  # This config is specific to lscr.io/mariadb
  umami-postgresql:
    image: postgres:15-alpine
    container_name: umami-postgresql
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - umami-postgresql-db:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
      interval: 5s
      timeout: 5s

This Docker Compose file sets up Umami Analytics with a PostgreSQL database backend. Make sure to adjust the file paths and environment variables according to your setup.

Maybe 5s health check interval is way too much and it outputs data to /var/log/messages at pace of 100MB per week.

Database is not accessible from internet so obvious credentials are not critical.

Generate and Store the App Secret

openssl rand 30 | openssl base64 -A
# Example output : grYw1gf2CurwJqgyuVCJD9A9xa7pDKzvA1kmzDry

Add the generated secret to your .env file for use by your Umami container:

UMAMI_SECRET=grYw1gf2CurwJqgyuVCJD9A9xa7pDKzvA1kmzDry

Start Umami Analytics

podman-compose -f docker-compose-umami-postgre.yml up # -d is optional, i suggest to see log for the first time

This will start the Umami Analytics container along with the PostgreSQL database container.

Access the Umami Analytics Web Interface

If everything works (no unami/umami typo, no failing database conversion script on empty mysql database), you should be able to connect to web interface at port 8083 http://localhost:8083/.

Initial Umami configuration

Now make sure to change password (👤, Profile) to something strong as this site will be accessible from internet. Don’t google the most popular passwords of 2024 :-). Default is admin/umami.

Now navigate to Settings -> Websites and add yours, for example name: dev-blog, domain: wwww.pavelp.cz. Click edit and there is website id and tracking code. Tracking code can be used directly on static website, just put into into <body> section.

Configure Cloudflare Tunnel

Add Cloudflare tunnel from a new subdomain to umami container

This step is necessary to connect to your Umami site from the internet, which is needed to execute the tracking JavaScript hosted on your site.

Navigate through Networks, Tunnels, and click the three dots at the end of the row corresponding to your target host. On the next page specific to the target host, select the “Public Hostname” tab, and add a new entry with the following details:

Key	Value	Note
Subdomain	t	I avoided tracker because of AdBlock etc
Domain	pavelp.cz
Path		empty
Type	HTTP	from tunnel to container
URL	umami:3000	host inside docker network

Upgrade Jekyll

There’s an article with sections dealing with Jekyll/Chirpy upgrades (install process, troubleshooting)

The most fun part is dealing with cached javascript files, that are causing malfunction of search and table of content. It’s necessary to turn Cloudflare into debug mode and purge cache.

Then run browser in a private tab.

Integrate Umami into Jekyll

• Fill in your own data into _config.yml to integrate Umami analytics
  (search for umami in config file)

  umami:
    id: "19e0f843-ddd1-4841-b112-e21f6a750770" # fill in your Umami ID
    domain: "https://t.pavelp.cz"              # fill in your Umami domain
  

• Ensure JEKYLL_ENV=production environment variable is set when running jekyll build to apply production specific features such as web analytics.

• Update Your Deployment Script

  If you’re using a deployment script to publish your Jekyll-Chirpy site, make sure to incorporate the JEKYLL_ENV=production environment variable. Here’s an example of how you can update your deployment script:

  #!/usr/bin/dash
  # Updates jekyll site in container
  
  target="nginx:/config/www"
  
  # New blog based on chirpy theme, used since 2023-06-24
  source="/home/pavel/dev-blog"
  cd $source
  echo "👷 Rebuilding static web content ..."
  JEKYLL_ENV=production jekyll build || exit
  echo "🔥 Deleting old content, don't panic! ..."
  podman exec nginx sh -c "cd /config/www && rm -rf *"
  echo "🚚 Copying new content ..."
  
  podman cp ~/bin/ip.php $target
  podman cp _site/. $target
  # The following lines added 2024-03-18.
  # Google authentication ID removed for purpose of this example.
  podman cp ~/jekyll/googleXXXXXX.html nginx:/config/www
  podman cp ~/jekyll/BingSiteAuth.xml nginx:/config/www
  

Troubleshooting

Setting up a self-hosted analytics solution can sometimes be challenging. Here are some common issues you might encounter and their potential solutions:

Docker Containers and Database related issues

Log Analysis

If something goes wrong, log analysis is helpful. Here are commands to check the logs for the Umami service and its database:

podman logs umami
podman logs umami-postresql

To monitor logs in real-time during setup, execute:

podman-compose -f docker-compose-umami-postgre.yml up

Skipping the usual -d flag allows you to observe the logs in real-time, making it easier to catch and address errors as they occur.

Common Database Issues

You may encounter several issues related to database configuration:

• Typographical Errors: Double-check your connection strings for typographical errors such as umami versus unami.
• Port Collisions: The default port 3000 might conflict with other services like Gitea. Adjusting the port in your docker-compose file to something like 8083 can prevent this issue.
• Backend Compatibility: MySQL/MariaDB was problematic in my setup; switching to a PostgreSQL backend resolved these issues.

Caching Issues After Jekyll Upgrade

Upgrading Jekyll-Chirpy or modifying your site’s content can lead to issues due to cached JavaScript and Style Sheet files. These might affect features like the search function, table of contents, or even the overall page layout and style.

To tackle caching problems:

• Enable Cloudflare Debug Mode: This allows you to monitor what content is being served to your users.
• Purge Cache: Clearing Cloudflare’s cache ensures that all users see the latest version of your site without interference from previously cached files.
• Private Browser Window: Accessing your site from a private browser window helps to bypass any locally cached files, offering a clean slate to verify the current site’s behavior. Also Ctrl+F5 may work.

Final Notes on Jekyll Configuration

A crucial but undocumented feature I discovered involves setting the JEKYLL_ENV=production environment variable. This setting is essential for making sure Jekyll operates under production settings, which can influence how your website is generated and what features are included.

This was discovered by looking into source code of _includes/js-selector.html, in order to find out why analytics do not work at all.

Addendum: Short Experience with Unami

Added 2024-05-23

How am I happy with Umami? Actually not much.

I have three other source of statistics other than Umami. Let’s compare them.

• Cloudflare: with free plan it’s useless. I can’t even separate NextCloud and other trafic, because traffic is filtered only by top level domain.
• Bing Webmaster Tool: It’s quite useful. I can see how many times page was displayed and how many clicks I receieved from certain keywords. Hopefully, unlike on Google, it’s quite easy to find some of my articles using Bing. Also it displays some problems such as duplicate H1 tags, titles or description too long. Problem of bing is that according that stats, I have like 25 visits in 3 months and most of them was about Arduino data logger, curiously using variety of keywords. That’s surprisign, I assume these articles are extremelly common.
• Google Search Console: This one is weird. Graph says I have roughly 2 clicks per day in last three months, but on the other hand, keywords suggest that I have 11 clicks in 3 months. Most visited articles seem to be about Gitea and Zimaboard - which are personal notes and I don’t think they are useful in general, some parts could be, but these are about specific tasks: first things after install, grub install, …
• Umami: This suggest 19 visits from Google in 10 days, which corresponds to graph and 2 visits per day. Visited pages are somewhat different too: raspberry and nokia display, zimaboard, logarex slide rules, then jekyll and then gitea. 2nd source of visitors are comming via duckduckgo, which uses bing (knowledge discovered today due to bing outage). Here most visited pages are zimaboard, Czech article about cloudflare - google does not even index English one. Maybe because it mentions that it’s automagically translated. Curiously most of duckduckgo users use Firefox.

Now what’s the problem with Umami?

Basically all I can get is which pages are the most visited and domain that refers to them. I can’t see search keywords and I can’t see which page on that domain links to my page: I can see only top-level domain such as google, reddit or github.

Also, I use blog for my own reference and my visits can significantly influence results, unless I’m using separate environment.

Good to know is that obviously google search console does not give accurate results and that despite low traffic comes through Bing (roughly two visitors per week), more of them comes through duckduckgo.

Screenshot

Umami analytics screenshot

References

• Jekyll Enviroments