From a7526415769d1693ceda19af1cbd2dd8852aed5a Mon Sep 17 00:00:00 2001
From: Chris Raible <chris@ghost.org>
Date: Mon, 14 Jul 2025 19:28:31 -0700
Subject: [PATCH] Added traffic analytics configuration for file based salt
 store (#26)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ref https://linear.app/ghost/issue/PROD-2300/add-file-based-salt-store-for-self-hosters

In the analytics service, we generate user signatures based on a randomly generated salt per site_uuid. The salts are regenerated every day at midnight UTC so we can't pass a static value, and they need to be persisted throughout the day so the same user (based on IP and user agent) will generate the same signature in any given day.

We use an adapter-like pattern for the persistence of the salts — the default is a MemoryStore intended for local development, and we use Firestore in production. The MemoryStore appears to work well enough, but if the analytics service container is rebooted (i.e. during an update), all the salts from the current day will be lost, and it will skew the "unique visitors" and related metrics.

This PR adds the configuration to use a simple file based store for the salts, and a volume mounted into the Traffic Analytics service for persistent storage. This was the salts are persisted across container reboots, which avoids skewing the unique visitors metrics.

There are no additional setup steps required — all sites can use the same configuration, and the volumes are managed by docker compose.
---
 compose.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/compose.yml b/compose.yml
index 3aafdc4..b1bc3be 100644
--- a/compose.yml
+++ b/compose.yml
@@ -88,9 +88,13 @@ services:
     restart: always
     expose:
       - "3000"
+    volumes:
+      - traffic_analytics_data:/data
     environment:
       NODE_ENV: production
       PROXY_TARGET: ${TINYBIRD_API_URL:-https://api.tinybird.co}/v0/events
+      SALT_STORE_TYPE: ${SALT_STORE_TYPE:-file}
+      SALT_STORE_FILE_PATH: /data/salts.json
       TINYBIRD_TRACKER_TOKEN: ${TINYBIRD_TRACKER_TOKEN:-}
       LOG_LEVEL: debug
     profiles: [analytics]
@@ -198,6 +202,7 @@ volumes:
   caddy_config:
   tinybird_files:
   tinybird_home:
+  traffic_analytics_data:
 
 networks:
   ghost_network: