← Zurück zum Blog

Traceflair selbst hosten mit Docker: Eine vollständige Anleitung

· 10 Min. Lesezeit

Das Self-Hosting Ihrer Analysen bietet Ihnen etwas, das keine SaaS-Plattform kann: vollständige Kontrolle über Ihre Daten. Jeder Seitenaufruf, jede Sitzungsaufzeichnung und jede Heatmap bleibt auf Ihren Servern. Keine Drittanbieter-Datenverarbeiter, keine grenzüberschreitenden Datentransfers und kein Anbieter, der morgen seine Datenschutzrichtlinien ändern könnte. Diese Anleitung führt Sie durch die Bereitstellung von Traceflair auf Ihrer eigenen Infrastruktur mit Docker Compose.

Warum Ihre Analysen selbst hosten

Datenhoheit

Wenn Analysedaten bei einem Drittanbieter-Dienst liegen, unterliegen sie dessen Rechtsordnung, Richtlinien und Sicherheitspraktiken. Self-Hosting bedeutet, dass Ihre Daten Ihren Richtlinien unterliegen, in der von Ihnen gewählten Rechtsordnung gespeichert werden und nur für Ihr Team zugänglich sind. Für Organisationen in regulierten Branchen wie Gesundheitswesen, Finanzwesen oder Behörden ist Self-Hosting oft nicht nur eine Vorliebe, sondern eine Anforderung.

Kostenkontrolle

SaaS-Analysepreise skalieren mit dem Traffic. Eine Website mit 10 Millionen monatlichen Seitenaufrufen zahlt möglicherweise Hunderte oder Tausende Euro pro Monat für kommerzielle Analysen mit Session Replay. Das Self-Hosting von Traceflair auf einem Server für 20-50 Euro pro Monat bewältigt das gleiche Volumen. Die Kosten steigen nicht mit dem Traffic; sie steigen nur, wenn Sie mehr Serverressourcen benötigen.

Vereinfachte Compliance

Die DSGVO erfordert eine Rechtsgrundlage für die Übermittlung personenbezogener Daten an Dritte. Beim Self-Hosting gibt es keinen Dritten. Sie sind sowohl der Datenverantwortliche als auch der Auftragsverarbeiter. Dies eliminiert die Notwendigkeit von Auftragsverarbeitungsverträgen, Standardvertragsklauseln und Transfer-Folgenabschätzungen mit Ihrem Analyseanbieter. Lesen Sie mehr über den datenschutzorientierten Ansatz von Traceflair, um zu sehen, wie dies in der Praxis funktioniert.

Voraussetzungen

Stellen Sie vor dem Start sicher, dass Sie Folgendes haben:

  • Docker Engine 20.10+ und Docker Compose v2 auf Ihrem Server installiert. Beides ist in Docker Desktop für die Entwicklung enthalten, oder installieren Sie Docker Engine direkt auf Linux-Servern.
  • Einen Server oder VPS mit mindestens 2GB RAM und 2 CPU-Kernen. Für Produktions-Workloads mit Session Replay werden 4GB RAM empfohlen. Jeder große Cloud-Anbieter (AWS, Hetzner, DigitalOcean, Linode) oder ein On-Premise-Server funktioniert.
  • Einen Domainnamen, der auf die IP-Adresse Ihres Servers zeigt, mit erreichbaren Ports 80 und 443. Dies benötigen Sie für HTTPS, das erforderlich ist, damit das Tracking-Script auf HTTPS-Websites funktioniert.
  • Grundlegende Kommandozeilen-Kenntnisse. Diese Anleitung verwendet Standard-Linux-Befehle.

Sie müssen PostgreSQL oder Redis nicht separat installieren. Beides ist in der Docker-Compose-Konfiguration enthalten.

Schritt 1: Das Projektverzeichnis erstellen

Verbinden Sie sich per SSH mit Ihrem Server und erstellen Sie ein Verzeichnis für Traceflair:

mkdir -p /opt/traceflair
cd /opt/traceflair

Schritt 2: Die Umgebungsdatei erstellen

Erstellen Sie eine .env-Datei mit Ihrer Konfiguration. Diese Datei enthält sensible Werte, setzen Sie daher entsprechende Dateiberechtigungen:

# /opt/traceflair/.env

# Erforderlich: ein zufälliger String zum Signieren von JWT-Tokens.
# Generieren Sie einen mit: openssl rand -hex 32
JWT_SECRET=ihr-zufaelliger-schluessel

# Datenbankkonfiguration (verwendet von PostgreSQL und dem Server)
POSTGRES_USER=traceflair
POSTGRES_PASSWORD=ein-starkes-datenbank-passwort
POSTGRES_DB=traceflair
DATABASE_URL=postgresql://traceflair:ein-starkes-datenbank-passwort@postgres:5432/traceflair

# Redis (verwendet für Session-Caching und Rate Limiting)
REDIS_URL=redis://redis:6379

# Serverkonfiguration
NODE_ENV=production
PORT=3001

# Optional: Stripe-Abrechnung (leer lassen zum Deaktivieren)
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

# Optional: PayPal-Abrechnung (leer lassen zum Deaktivieren)
PAYPAL_CLIENT_ID=
PAYPAL_CLIENT_SECRET=

# Optional: E-Mail via Resend (leer lassen für Konsolenausgabe)
RESEND_API_KEY=

Setzen Sie restriktive Berechtigungen auf die Umgebungsdatei:

chmod 600 /opt/traceflair/.env

Schritt 3: Die Docker-Compose-Datei erstellen

Erstellen Sie die Datei docker-compose.yml, die den gesamten Stack definiert:

# /opt/traceflair/docker-compose.yml
version: "3.8"

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  server:
    image: traceflair/server:latest
    restart: unless-stopped
    ports:
      - "3001:3001"
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  dashboard:
    image: traceflair/dashboard:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    depends_on:
      - server

volumes:
  pgdata:
  redisdata:

Schritt 4: Den Stack starten

Starten Sie alle Dienste mit einem einzigen Befehl:

docker compose up -d

Docker wird die Images herunterladen (dies dauert beim ersten Start ein bis zwei Minuten), PostgreSQL und Redis starten, auf deren Bereitschaft warten und dann den Traceflair-Server und das Dashboard starten. Beobachten Sie die Logs, um zu bestätigen, dass alles korrekt startet:

docker compose logs -f server

Sie sollten eine Ausgabe sehen, die anzeigt, dass der Server sich mit PostgreSQL und Redis verbunden hat, Datenbankmigrationen durchgeführt hat und auf Port 3001 lauscht. Drücken Sie Ctrl+C, um das Log-Verfolgen zu beenden.

Schritt 5: Einen Reverse Proxy mit HTTPS einrichten

Der Traceflair-Server und das Dashboard laufen auf den Ports 3001 bzw. 3000. Für den Produktionsbetrieb benötigen Sie einen Reverse Proxy, der HTTPS-Terminierung übernimmt. Hier ist eine minimale nginx-Konfiguration:

# /etc/nginx/sites-available/traceflair
server {
    listen 443 ssl http2;
    server_name analytics.ihredomain.com;

    ssl_certificate /etc/letsencrypt/live/analytics.ihredomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.ihredomain.com/privkey.pem;

    # Dashboard
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # API-Server
    location /v1/ {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # API-Auth und andere Server-Routen
    location /api/ {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Verwenden Sie Certbot, um ein kostenloses Let's-Encrypt-Zertifikat zu erhalten:

sudo certbot --nginx -d analytics.ihredomain.com

Schritt 6: Die Installation überprüfen

Überprüfen Sie bei laufendem Stack und konfiguriertem Reverse Proxy jede Komponente:

API-Health-Endpunkt prüfen:

curl https://analytics.ihredomain.com/v1/health
# Erwartet: {"status":"ok"}

Dashboard aufrufen: Öffnen Sie https://analytics.ihredomain.com in Ihrem Browser. Sie sollten den Traceflair-Anmeldebildschirm sehen. Erstellen Sie Ihr erstes Admin-Konto über den Einrichtungsassistenten.

Tracking-Script zu Ihrer Website hinzufügen: Nachdem Sie eine Website im Dashboard erstellt haben, fügen Sie das Traceflair-Script zu Ihren Seiten hinzu:

<script
  src="https://analytics.ihredomain.com/v1/script.js"
  data-site-id="your-site-id"
  data-consent="opt-in">
</script>

Überprüfen, ob Events empfangen werden: Besuchen Sie Ihre Website in einem Browser und prüfen Sie dann das Traceflair-Dashboard. Sie sollten den Seitenaufruf innerhalb weniger Sekunden sehen.

Referenz der Umgebungsvariablen

Hier finden Sie eine vollständige Referenz aller Umgebungsvariablen, die der Server akzeptiert:

  • DATABASE_URL (erforderlich) — PostgreSQL-Verbindungsstring.
  • JWT_SECRET (erforderlich) — Zufälliger String zum Signieren von Authentifizierungs-Tokens. Verwenden Sie mindestens 32 Zeichen.
  • REDIS_URL (optional) — Redis-Verbindungsstring. Standard ist redis://localhost:6379. Wird für Session-Caching und Rate Limiting verwendet.
  • PORT (optional) — Server-Port. Standard ist 3001.
  • NODE_ENV (optional) — Auf production setzen für Produktions-Deployments. Aktiviert Sicherheits-Header und deaktiviert Debug-Logging.
  • STRIPE_SECRET_KEY (optional) — Stripe-API-Schlüssel für die Abrechnung. Leer lassen, um Stripe-Abrechnung zu deaktivieren.
  • STRIPE_WEBHOOK_SECRET (optional) — Stripe Webhook-Signierungsschlüssel.
  • PAYPAL_CLIENT_ID (optional) — PayPal Client-ID. Leer lassen, um PayPal-Abrechnung zu deaktivieren.
  • PAYPAL_CLIENT_SECRET (optional) — PayPal Client-Secret.
  • RESEND_API_KEY (optional) — Resend-API-Schlüssel für transaktionale E-Mails. Wenn nicht gesetzt, werden E-Mails in der Konsole ausgegeben.

Traceflair aktualisieren

Um auf die neueste Version zu aktualisieren, laden Sie die neuen Images herunter und starten Sie neu:

cd /opt/traceflair
docker compose pull
docker compose up -d

Der Server führt beim Start automatisch Datenbankmigrationen durch, sodass Schema-Updates ohne manuellen Eingriff angewendet werden. Es empfiehlt sich, Ihre PostgreSQL-Daten vor einem Update zu sichern:

docker compose exec postgres pg_dump -U traceflair traceflair > backup-$(date +%Y%m%d).sql

Ihre Daten sichern

Ihre Analysedaten werden an zwei Stellen gespeichert: PostgreSQL (Events, Sitzungen, Nutzerdaten) und Redis (flüchtige Caches). Nur PostgreSQL muss gesichert werden. Richten Sie einen täglichen Cron-Job ein:

# Zu crontab hinzufügen: crontab -e
0 3 * * * cd /opt/traceflair && docker compose exec -T postgres pg_dump -U traceflair traceflair | gzip > /opt/traceflair/backups/traceflair-$(date +\%Y\%m\%d).sql.gz

Nächste Schritte

Mit Traceflair auf Ihrer Infrastruktur haben Sie eine vollständige Analyseplattform unter Ihrer Kontrolle. Hier sind einige nächste Schritte:

Wenn Sie Fragen zum Self-Hosting haben oder Hilfe bei Ihrem Deployment benötigen, wenden Sie sich an unser Team. Für Teams, die keine Infrastruktur verwalten möchten, bieten wir auch eine gehostete Version mit denselben Funktionen und einem großzügigen kostenlosen Plan.

Ihre Nutzer sagen Ihnen etwas. Hören Sie zu.

Kostenlos starten. Keine Kreditkarte nötig. In unter 5 Minuten eingerichtet.

Kostenlos starten