Auto-héberger HitKeep avec Docker Compose

Docker Compose fournit un déploiement reproductible et versionnable avec des volumes persistants. Vos données d’analyse restent dans un volume Docker nommé sur votre serveur, notamment la base partagée hitkeep.db et les bases propres aux espaces créées sous tenants/*/hitkeep.db.

Cette page explique comment exécuter HitKeep comme service auto-hébergé. Pour l’environnement de contribution avec rechargement à chaud, Go, Air, Angular, Mailpit et des données de démonstration dans Docker, consultez le guide de contribution.

Les images HitKeep sont publiées dans deux registres à chaque version :

Registre	Image
Docker Hub	pascalebeier/hitkeep
GitHub Container Registry	ghcr.io/pascalebeier/hitkeep

Les deux registres proposent les mêmes images multiplateformes (linux/amd64, linux/arm64) accompagnées d’attestations de provenance signées. Choisissez celui qui convient à votre réseau ou à vos limites de téléchargement.

Ne placez pas les secrets dans les fichiers Compose

Transmettez les valeurs sensibles (HITKEEP_JWT_SECRET, mots de passe SMTP) par des variables d’environnement, un fichier .env ou des secrets Docker, jamais en clair dans compose.yml ni dans les options de commande. Excluez .env du contrôle de version. Pour une gestion plus stricte, utilisez les secrets Docker.

Démarrage rapide

Un déploiement tient dans deux fichiers du même répertoire : compose.yml (copiez-le tel quel, sans le modifier) et .env (qui contient vos valeurs). Au démarrage, Compose remplace chaque ${VARIABLE} de compose.yml par la ligne correspondante de .env.

1. Créer compose.yml

Créez un répertoire et ajoutez-y ce fichier compose.yml. Cette base conserve les données actives, les archives de rétention et les instantanés automatiques dans trois volumes nommés distincts. Le même fichier est maintenu dans le dépôt sous examples/compose.yml, avec le fichier examples/.env.example, si vous préférez les copier depuis la source.

services:
  hitkeep:
    image: pascalebeier/hitkeep:latest
    container_name: hitkeep
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - hitkeep_data:/var/lib/hitkeep/data
      - hitkeep_archive:/var/lib/hitkeep/archive
      - hitkeep_backups:/var/lib/hitkeep/backups
    environment:
      # Public URL must match the browser-visible origin, including any path prefix.
      HITKEEP_PUBLIC_URL: ${HITKEEP_PUBLIC_URL:-http://localhost:8080}
      # Required for stable sessions. Generate with: openssl rand -hex 32
      HITKEEP_JWT_SECRET: ${HITKEEP_JWT_SECRET:?set HITKEEP_JWT_SECRET in .env}
      # Behind a reverse proxy, set to the proxy network CIDR so real client IPs are used.
      HITKEEP_TRUSTED_PROXIES: ${HITKEEP_TRUSTED_PROXIES:-} # config-default-override: require an explicit trusted proxy network
      # Keep live data, retention archives, and backup snapshots on persistent volumes.
      HITKEEP_DB_PATH: /var/lib/hitkeep/data/hitkeep.db
      HITKEEP_DATA_PATH: /var/lib/hitkeep/data
      HITKEEP_ARCHIVE_PATH: /var/lib/hitkeep/archive
      HITKEEP_BACKUP_PATH: /var/lib/hitkeep/backups
      HITKEEP_BACKUP_INTERVAL: ${HITKEEP_BACKUP_INTERVAL:-60}
      HITKEEP_BACKUP_RETENTION: ${HITKEEP_BACKUP_RETENTION:-24}
      # Optional OSS spam-list refresh. Disable for fully offline/air-gapped installs.
      HITKEEP_SPAM_FILTER_AUTO_UPDATE: "true"
      HITKEEP_SPAM_FILTER_UPDATE_INTERVAL: ${HITKEEP_SPAM_FILTER_UPDATE_INTERVAL:-1440}
      HITKEEP_SPAM_FILTER_PATH: /var/lib/hitkeep/data/spam-filter.json
      # Optional read-only MCP endpoint for governed assistant/reporting access.
      HITKEEP_MCP_ENABLED: "true"
      HITKEEP_MCP_PATH: /mcp
      HITKEEP_MCP_MAX_RANGE_DAYS: ${HITKEEP_MCP_MAX_RANGE_DAYS:-366}
      # Optional AI model route for Opportunity enrichment. Provider credentials
      # use the selected goAI provider's own env vars, such as OPENAI_API_KEY.
      HITKEEP_AI_ENABLED: ${HITKEEP_AI_ENABLED:-false}
      HITKEEP_AI_PROVIDER: ${HITKEEP_AI_PROVIDER:-}
      HITKEEP_AI_MODEL: ${HITKEEP_AI_MODEL:-}
      HITKEEP_AI_BASE_URL: ${HITKEEP_AI_BASE_URL:-}
      HITKEEP_AI_REGION: ${HITKEEP_AI_REGION:-}
      HITKEEP_AI_API_KEY: ${HITKEEP_AI_API_KEY:-}
      HITKEEP_AI_REQUEST_LIMIT: ${HITKEEP_AI_REQUEST_LIMIT:-100}
      HITKEEP_AI_TOKEN_LIMIT: ${HITKEEP_AI_TOKEN_LIMIT:-100000}
      HITKEEP_AI_BUDGET_WINDOW: ${HITKEEP_AI_BUDGET_WINDOW:-1440}
      # Optional Google Search Console OAuth integration.
      HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_ID: ${HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_ID:-}
      HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET: ${HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET:-}
      HITKEEP_GOOGLE_SEARCH_CONSOLE_REDIRECT_URL: ${HITKEEP_GOOGLE_SEARCH_CONSOLE_REDIRECT_URL:-}
      # Optional Google, GitHub, and Microsoft social sign-in.
      HITKEEP_SOCIAL_GOOGLE_CLIENT_ID: ${HITKEEP_SOCIAL_GOOGLE_CLIENT_ID:-}
      HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET: ${HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET:-}
      HITKEEP_SOCIAL_GITHUB_CLIENT_ID: ${HITKEEP_SOCIAL_GITHUB_CLIENT_ID:-}
      HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET: ${HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET:-}
      HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID: ${HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID:-}
      HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET: ${HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET:-}
      HITKEEP_SOCIAL_MICROSOFT_TENANT: ${HITKEEP_SOCIAL_MICROSOFT_TENANT:-common}
      # SMTP powers invites, password reset, email reports, and security mail.
      HITKEEP_MAIL_HOST: ${HITKEEP_MAIL_HOST:-}
      HITKEEP_MAIL_PORT: ${HITKEEP_MAIL_PORT:-587}
      HITKEEP_MAIL_USERNAME: ${HITKEEP_MAIL_USERNAME:-}
      HITKEEP_MAIL_PASSWORD: ${HITKEEP_MAIL_PASSWORD:-}
      HITKEEP_MAIL_ENCRYPTION: ${HITKEEP_MAIL_ENCRYPTION:-tls}
      HITKEEP_MAIL_FROM_ADDRESS: ${HITKEEP_MAIL_FROM_ADDRESS:-hitkeep@localhost}
      HITKEEP_MAIL_FROM_NAME: ${HITKEEP_MAIL_FROM_NAME:-HitKeep}

volumes:
  hitkeep_data: {}
  hitkeep_archive: {}
  hitkeep_backups: {}

2. Créer .env

Commencez par générer la clé de signature de session dans votre terminal, puis copiez le résultat :

openssl rand -hex 32

Si openssl n’est pas installé, head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n'; echo produit une valeur équivalente sur toute machine Linux.

Créez ensuite, avec votre éditeur, un fichier .env à côté de compose.yml et renseignez vos valeurs :

# Required. Paste the generated 64-character hex string here.
HITKEEP_JWT_SECRET=paste-the-generated-value-here
# Required. The exact URL you open in the browser. Behind a reverse proxy
# this is your public domain, e.g. https://analytics.example.com
HITKEEP_PUBLIC_URL=http://localhost:8080
# Optional social sign-in. Set both values for each provider you enable.
HITKEEP_SOCIAL_GOOGLE_CLIENT_ID=
HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET=
HITKEEP_SOCIAL_GITHUB_CLIENT_ID=
HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET=
HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID=
HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET=
HITKEEP_SOCIAL_MICROSOFT_TENANT=common
# Optional SMTP. Powers invites, password resets, and email reports.
# Leave the values empty to run without outbound mail.
HITKEEP_MAIL_HOST=
HITKEEP_MAIL_PORT=587
HITKEEP_MAIL_USERNAME=
HITKEEP_MAIL_PASSWORD=
HITKEEP_MAIL_FROM_ADDRESS=hitkeep@localhost
HITKEEP_MAIL_FROM_NAME=HitKeep

.env n’est pas un script shell

.env contient de simples lignes CLÉ=valeur : ni echo, ni accolades, ni substitution $(commande). Docker Compose le lit littéralement ; une commande collée dans le fichier devient donc du texte. Les guillemets sont inutiles. Excluez ce fichier du contrôle de version en l’ajoutant à .gitignore.

Les deux fichiers emploient volontairement une syntaxe différente : compose.yml est en YAML et écrit CLÉ: valeur, tandis que .env utilise le format dotenv CLÉ=valeur.

3. Démarrer HitKeep

docker compose up -d
docker compose logs -f hitkeep

Les lignes de journal Starting HitKeep et HTTP server starting indiquent que le service est démarré.

4. Se connecter

Ouvrez HITKEEP_PUBLIC_URL dans votre navigateur. L’assistant crée le premier compte, qui devient automatiquement propriétaire de l’instance, puis vous aide à ajouter votre premier site.

La base se trouve dans le volume hitkeep_data. Le répertoire de récupération automatique par défaut, /var/lib/hitkeep/data/recovery, reste donc lui aussi persistant. Les archives de rétention sont dans hitkeep_archive et les instantanés automatiques dans hitkeep_backups. Les paquets de récupération contiennent des données de base, ne suivent pas la rotation des sauvegardes et doivent être protégés puis supprimés séparément. MCP est exposé sous /mcp, mais les clients ont toujours besoin de jetons d’API porteur limités à leur périmètre.

MCP est facultatif dans le produit et activé dans cet exemple Compose pour les équipes qui souhaitent un accès en lecture seule à leurs assistants ou rapports. Supprimez HITKEEP_MCP_ENABLED, HITKEEP_MCP_PATH et HITKEEP_MCP_MAX_RANGE_DAYS si vous ne publiez pas de point de terminaison MCP.

L’enrichissement par un fournisseur d’IA est facultatif et désactivé par défaut. Conservez HITKEEP_AI_ENABLED=false jusqu’à avoir choisi un fournisseur et un modèle, configuré les identifiants et défini des plafonds locaux. Consultez Recommandations d’opportunités et la configuration des modèles d’IA.

La connexion sociale est facultative. Définissez l’identifiant et le secret client de chaque fournisseur voulu, puis enregistrez l’URL de rappel exacte dérivée de HITKEEP_PUBLIC_URL. Le guide Connexion sociale couvre l’enregistrement, les rappels, la vérification de l’adresse e-mail, les invitations, la MFA et l’association de comptes. HITKEEP_SOCIAL_SIGNUP_ENABLED n’ouvre pas l’inscription publique sur une instance auto-hébergée.

Les données de ville, de fournisseur et d’ASN sont intégrées aux images publiées. Les déploiements Compose n’ont pas besoin de IP2LOCATION_DOWNLOAD_TOKEN.

Vérifier le déploiement

Confirmez que Compose voit un service en cours d’exécution et que les deux sondes réussissent :

docker compose ps
curl --fail http://localhost:8080/healthz
curl --fail http://localhost:8080/readyz
docker compose logs --since=5m hitkeep

/healthz confirme que le processus est actif. /readyz confirme que la base partagée et toutes les bases d’espace ouvertes sont prêtes. Si HitKeep n’est accessible que par le proxy inverse, interrogez plutôt son URL visible dans le navigateur.

Mettre à niveau

Lisez les dernières notes de version et vérifiez qu’une sauvegarde actuelle existe. Téléchargez ensuite l’image stable actuelle et recréez uniquement le service HitKeep :

docker compose pull hitkeep
docker compose up -d hitkeep
docker compose ps
curl --fail http://localhost:8080/readyz

Compose conserve les volumes nommés de données, d’archives et de sauvegardes quand il remplace le conteneur. N’exécutez pas docker compose down -v pendant une mise à niveau : -v supprime ces volumes.

Configurer un proxy inverse

En production, placez HitKeep derrière un proxy inverse pour HTTPS. Configurez les proxys de confiance afin d’utiliser les véritables adresses IP clientes pour l’analyse et la limitation de débit.

HITKEEP_PUBLIC_URL peut inclure un préfixe de chemin. Par exemple, utilisez HITKEEP_PUBLIC_URL=https://www.example.net/hitkeep/ pour monter HitKeep sous un site existant. Le proxy doit publier le même préfixe, comme /hitkeep/*, et le transmettre au conteneur. HitKeep sert alors sous ce préfixe la base du tableau de bord, l’API, hk.js, hk-vitals.js et les points d’ingestion.

Caddy

caddy-docker-proxy gère automatiquement HTTPS avec Let’s Encrypt et génère sa configuration à partir des labels Docker. Utilisez de préférence un réseau d’entrée dédié et n’accordez votre confiance qu’à sa plage CIDR dans HitKeep.

services:
caddy:
  image: lucaslorentz/caddy-docker-proxy:2.9-alpine
  container_name: caddy-proxy
  restart: unless-stopped
  ports:
    - "80:80"
    - "443:443"
    - "443:443/udp"
  environment:
    CADDY_INGRESS_NETWORKS: caddy
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
    - caddy_data:/data
    - caddy_config:/config
  networks:
    - caddy
  labels:
    caddy.email: ${CADDY_EMAIL:?set in .env}

hitkeep:
  image: pascalebeier/hitkeep:latest
  container_name: hitkeep
  restart: unless-stopped
  networks:
    - caddy
  volumes:
    - hitkeep_data:/var/lib/hitkeep/data
    - hitkeep_archive:/var/lib/hitkeep/archive
    - hitkeep_backups:/var/lib/hitkeep/backups
  environment:
    HITKEEP_NODE_NAME: leader
    # Public URL must match the HTTPS origin served by Caddy, including any path prefix.
    HITKEEP_PUBLIC_URL: ${HITKEEP_PUBLIC_URL:?set in .env}
    # Required for stable sessions. Generate with: openssl rand -hex 32
    HITKEEP_JWT_SECRET: ${HITKEEP_JWT_SECRET:?set in .env}
    # Must be the Caddy network CIDR. This controls real visitor IP, geo/network metadata,
    # country exclusions, rate limiting, and spam checks.
    HITKEEP_TRUSTED_PROXIES: ${HITKEEP_TRUSTED_PROXIES:?set to your caddy network CIDR}
    # Keep live data, retention archives, and backup snapshots on persistent volumes.
    HITKEEP_DB_PATH: /var/lib/hitkeep/data/hitkeep.db
    HITKEEP_DATA_PATH: /var/lib/hitkeep/data
    HITKEEP_ARCHIVE_PATH: /var/lib/hitkeep/archive
    HITKEEP_BACKUP_PATH: /var/lib/hitkeep/backups
    HITKEEP_BACKUP_INTERVAL: ${HITKEEP_BACKUP_INTERVAL:-60}
    HITKEEP_BACKUP_RETENTION: ${HITKEEP_BACKUP_RETENTION:-24}
    # Optional OSS spam-list refresh. Disable for fully offline/air-gapped installs.
    HITKEEP_SPAM_FILTER_AUTO_UPDATE: "true"
    HITKEEP_SPAM_FILTER_UPDATE_INTERVAL: ${HITKEEP_SPAM_FILTER_UPDATE_INTERVAL:-1440}
    HITKEEP_SPAM_FILTER_PATH: /var/lib/hitkeep/data/spam-filter.json
    # Optional read-only MCP endpoint for governed assistant/reporting access.
    HITKEEP_MCP_ENABLED: "true"
    HITKEEP_MCP_PATH: /mcp
    HITKEEP_MCP_MAX_RANGE_DAYS: ${HITKEEP_MCP_MAX_RANGE_DAYS:-366}
    # Optional AI model route for Opportunity enrichment. Leave disabled until a provider is configured.
    HITKEEP_AI_ENABLED: ${HITKEEP_AI_ENABLED:-false}
    HITKEEP_AI_PROVIDER: ${HITKEEP_AI_PROVIDER:-}
    HITKEEP_AI_MODEL: ${HITKEEP_AI_MODEL:-}
    HITKEEP_AI_BASE_URL: ${HITKEEP_AI_BASE_URL:-}
    HITKEEP_AI_REGION: ${HITKEEP_AI_REGION:-}
    HITKEEP_AI_API_KEY: ${HITKEEP_AI_API_KEY:-}
    HITKEEP_AI_REQUEST_LIMIT: ${HITKEEP_AI_REQUEST_LIMIT:-100}
    HITKEEP_AI_TOKEN_LIMIT: ${HITKEEP_AI_TOKEN_LIMIT:-100000}
    HITKEEP_AI_BUDGET_WINDOW: ${HITKEEP_AI_BUDGET_WINDOW:-1440}
    # Optional Google Search Console OAuth integration.
    HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_ID: ${HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_ID:-}
    HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET: ${HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET:-}
    HITKEEP_GOOGLE_SEARCH_CONSOLE_REDIRECT_URL: ${HITKEEP_GOOGLE_SEARCH_CONSOLE_REDIRECT_URL:-}
    # Optional Google, GitHub, and Microsoft social sign-in.
    HITKEEP_SOCIAL_GOOGLE_CLIENT_ID: ${HITKEEP_SOCIAL_GOOGLE_CLIENT_ID:-}
    HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET: ${HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET:-}
    HITKEEP_SOCIAL_GITHUB_CLIENT_ID: ${HITKEEP_SOCIAL_GITHUB_CLIENT_ID:-}
    HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET: ${HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET:-}
    HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID: ${HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID:-}
    HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET: ${HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET:-}
    HITKEEP_SOCIAL_MICROSOFT_TENANT: ${HITKEEP_SOCIAL_MICROSOFT_TENANT:-common}
    # SMTP powers invites, password reset, email reports, and security mail.
    HITKEEP_MAIL_HOST: ${HITKEEP_MAIL_HOST:-}
    HITKEEP_MAIL_PORT: ${HITKEEP_MAIL_PORT:-587}
    HITKEEP_MAIL_USERNAME: ${HITKEEP_MAIL_USERNAME:-}
    HITKEEP_MAIL_PASSWORD: ${HITKEEP_MAIL_PASSWORD:-}
    HITKEEP_MAIL_ENCRYPTION: ${HITKEEP_MAIL_ENCRYPTION:-tls}
    HITKEEP_MAIL_FROM_ADDRESS: ${HITKEEP_MAIL_FROM_ADDRESS:-hitkeep@localhost}
    HITKEEP_MAIL_FROM_NAME: ${HITKEEP_MAIL_FROM_NAME:-HitKeep}
  labels:
    caddy: ${HITKEEP_HOSTNAME:?set in .env}
    caddy.reverse_proxy: "{{upstreams 8080}}"
    caddy.encode: "zstd gzip"

volumes:
caddy_data: {}
caddy_config: {}
hitkeep_data: {}
hitkeep_archive: {}
hitkeep_backups: {}

networks:
caddy:
  external: true

Deux valeurs proviennent de votre terminal : le secret de session et la plage CIDR du réseau Caddy.

openssl rand -hex 32
docker network inspect caddy --format '{{(index .IPAM.Config 0).Subnet}}'

Créez ensuite le fichier .env dans votre éditeur :

# Required. Paste the generated 64-character hex string here.
HITKEEP_JWT_SECRET=paste-the-generated-value-here
HITKEEP_PUBLIC_URL=https://analytics.example.com
HITKEEP_HOSTNAME=analytics.example.com
CADDY_EMAIL=ops@example.com
# Paste the Caddy network subnet from the docker network inspect command.
HITKEEP_TRUSTED_PROXIES=paste-the-caddy-subnet-here
# Optional social sign-in. Set both values for each provider you enable.
HITKEEP_SOCIAL_GOOGLE_CLIENT_ID=
HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET=
HITKEEP_SOCIAL_GITHUB_CLIENT_ID=
HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET=
HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID=
HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET=
HITKEEP_SOCIAL_MICROSOFT_TENANT=common
HITKEEP_MAIL_HOST=smtp.example.com
HITKEEP_MAIL_PORT=587
HITKEEP_MAIL_USERNAME=postmaster@example.com
HITKEEP_MAIL_PASSWORD=change-me
HITKEEP_MAIL_FROM_ADDRESS=analytics@example.com
HITKEEP_MAIL_FROM_NAME=HitKeep

HITKEEP_TRUSTED_PROXIES doit correspondre à la plage CIDR du réseau du proxy inverse, et non à 0.0.0.0/0.

Pour un montage dans un sous-répertoire, alignez HITKEEP_PUBLIC_URL et le préfixe de route du proxy. Voici la route Caddy équivalente :

HITKEEP_PUBLIC_URL=https://www.example.net/hitkeep/
HITKEEP_HOSTNAME=www.example.net

www.example.net {
handle /hitkeep* {
  reverse_proxy hitkeep:8080
}
encode zstd gzip
}

nginx

Avec un nginx existant sur l’hôte, qui gère ses certificats, conservez le fichier compose.yml du démarrage rapide et dirigez nginx vers le port publié.

Apportez deux ajustements :

1. Dans compose.yml, liez le port à l’interface de bouclage afin que seul nginx local atteigne le conteneur :

    ports:
    - "127.0.0.1:8080:8080"

2. Dans .env, définissez l’URL publique sur le domaine servi par nginx et faites confiance au réseau Docker. Le trafic de l’hôte atteint le conteneur par la passerelle Docker, située dans la plage 172.16.0.0/12 :

HITKEEP_PUBLIC_URL=https://analytics.example.com
HITKEEP_TRUSTED_PROXIES=172.16.0.0/12

Ajoutez ensuite ce bloc serveur à nginx :

server {
  listen 443 ssl;
  http2 on;
  server_name analytics.example.com;

  # ssl_certificate / ssl_certificate_key as issued by certbot or your CA.

  location / {
      proxy_pass http://127.0.0.1:8080;
      proxy_http_version 1.1;
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Host $host;
      # Live dashboard updates stream over server-sent events.
      proxy_set_header Connection "";
      proxy_buffering off;
      proxy_read_timeout 300s;
  }
}

Rechargez nginx (nginx -t && systemctl reload nginx) et ouvrez https://analytics.example.com. Si tous les visiteurs semblent provenir de la même adresse privée, revoyez la configuration des proxys de confiance.

Traefik

Pour une pile Traefik existante, exposez HitKeep avec des labels :

services:
hitkeep:
  image: pascalebeier/hitkeep:latest
  restart: unless-stopped
  volumes:
    - hitkeep_data:/var/lib/hitkeep/data
    - hitkeep_archive:/var/lib/hitkeep/archive
    - hitkeep_backups:/var/lib/hitkeep/backups
  environment:
    # Public URL must match the HTTPS origin served by Traefik, including any path prefix.
    HITKEEP_PUBLIC_URL: ${HITKEEP_PUBLIC_URL:?set in .env}
    # Required for stable sessions. Generate with: openssl rand -hex 32
    HITKEEP_JWT_SECRET: ${HITKEEP_JWT_SECRET:?set in .env}
    # Must be the Traefik network CIDR. This controls real visitor IP, geo/network metadata,
    # country exclusions, rate limiting, and spam checks.
    HITKEEP_TRUSTED_PROXIES: ${HITKEEP_TRUSTED_PROXIES:?set to your traefik network CIDR}
    # Keep live data, retention archives, and backup snapshots on persistent volumes.
    HITKEEP_DB_PATH: /var/lib/hitkeep/data/hitkeep.db
    HITKEEP_DATA_PATH: /var/lib/hitkeep/data
    HITKEEP_ARCHIVE_PATH: /var/lib/hitkeep/archive
    HITKEEP_BACKUP_PATH: /var/lib/hitkeep/backups
    HITKEEP_BACKUP_INTERVAL: ${HITKEEP_BACKUP_INTERVAL:-60}
    HITKEEP_BACKUP_RETENTION: ${HITKEEP_BACKUP_RETENTION:-24}
    # Optional OSS spam-list refresh. Disable for fully offline/air-gapped installs.
    HITKEEP_SPAM_FILTER_AUTO_UPDATE: "true"
    HITKEEP_SPAM_FILTER_UPDATE_INTERVAL: ${HITKEEP_SPAM_FILTER_UPDATE_INTERVAL:-1440}
    HITKEEP_SPAM_FILTER_PATH: /var/lib/hitkeep/data/spam-filter.json
    # Optional read-only MCP endpoint for governed assistant/reporting access.
    HITKEEP_MCP_ENABLED: "true"
    HITKEEP_MCP_PATH: /mcp
    HITKEEP_MCP_MAX_RANGE_DAYS: ${HITKEEP_MCP_MAX_RANGE_DAYS:-366}
    # Optional AI model route for Opportunity enrichment. Leave disabled until a provider is configured.
    HITKEEP_AI_ENABLED: ${HITKEEP_AI_ENABLED:-false}
    HITKEEP_AI_PROVIDER: ${HITKEEP_AI_PROVIDER:-}
    HITKEEP_AI_MODEL: ${HITKEEP_AI_MODEL:-}
    HITKEEP_AI_BASE_URL: ${HITKEEP_AI_BASE_URL:-}
    HITKEEP_AI_REGION: ${HITKEEP_AI_REGION:-}
    HITKEEP_AI_API_KEY: ${HITKEEP_AI_API_KEY:-}
    HITKEEP_AI_REQUEST_LIMIT: ${HITKEEP_AI_REQUEST_LIMIT:-100}
    HITKEEP_AI_TOKEN_LIMIT: ${HITKEEP_AI_TOKEN_LIMIT:-100000}
    HITKEEP_AI_BUDGET_WINDOW: ${HITKEEP_AI_BUDGET_WINDOW:-1440}
    # Optional Google Search Console OAuth integration.
    HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_ID: ${HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_ID:-}
    HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET: ${HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET:-}
    HITKEEP_GOOGLE_SEARCH_CONSOLE_REDIRECT_URL: ${HITKEEP_GOOGLE_SEARCH_CONSOLE_REDIRECT_URL:-}
    # Optional Google, GitHub, and Microsoft social sign-in.
    HITKEEP_SOCIAL_GOOGLE_CLIENT_ID: ${HITKEEP_SOCIAL_GOOGLE_CLIENT_ID:-}
    HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET: ${HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET:-}
    HITKEEP_SOCIAL_GITHUB_CLIENT_ID: ${HITKEEP_SOCIAL_GITHUB_CLIENT_ID:-}
    HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET: ${HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET:-}
    HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID: ${HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID:-}
    HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET: ${HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET:-}
    HITKEEP_SOCIAL_MICROSOFT_TENANT: ${HITKEEP_SOCIAL_MICROSOFT_TENANT:-common}
    # SMTP powers invites, password reset, email reports, and security mail.
    HITKEEP_MAIL_HOST: ${HITKEEP_MAIL_HOST:-}
    HITKEEP_MAIL_PORT: ${HITKEEP_MAIL_PORT:-587}
    HITKEEP_MAIL_USERNAME: ${HITKEEP_MAIL_USERNAME:-}
    HITKEEP_MAIL_PASSWORD: ${HITKEEP_MAIL_PASSWORD:-}
    HITKEEP_MAIL_ENCRYPTION: ${HITKEEP_MAIL_ENCRYPTION:-tls}
    HITKEEP_MAIL_FROM_ADDRESS: ${HITKEEP_MAIL_FROM_ADDRESS:-hitkeep@localhost}
    HITKEEP_MAIL_FROM_NAME: ${HITKEEP_MAIL_FROM_NAME:-HitKeep}
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.hitkeep.rule=Host(`analytics.example.com`)"
    - "traefik.http.routers.hitkeep.entrypoints=websecure"
    - "traefik.http.routers.hitkeep.tls.certresolver=myresolver"
    - "traefik.http.services.hitkeep.loadbalancer.server.port=8080"

volumes:
hitkeep_data: {}
hitkeep_archive: {}
hitkeep_backups: {}

Domaines de suivi personnalisés

Les équipes auto-hébergées peuvent utiliser les domaines de suivi personnalisés avec tout proxy inverse qui termine TLS et préserve l’en-tête Host d’origine. Utilisez le mode TLS externe quand nginx, Traefik, un répartiteur de charge ou un autre processus ACME gère les certificats. Choisissez le profil Caddy pour une intégration guidée depuis le tableau de bord avec émission de certificats à la demande.

TLS externe avec nginx ou Traefik

Ajoutez ce paramètre HitKeep lorsque le proxy inverse gère déjà les certificats :

HITKEEP_CUSTOM_TRACKING_TLS_MODE: external

En mode externe, ajoutez chaque nom d’hôte de suivi au proxy avant que l’équipe clique sur Vérifier dans HitKeep. La sonde exige que https://<hostname>/hk.js renvoie le tracker avec un certificat valide.

Le dépôt HitKeep fournit des exemples sans Caddy :

• examples/nginx.custom-tracking.conf
• examples/compose.nginx-custom-tracking.yml
• examples/traefik.custom-tracking.yml
• examples/compose.traefik-custom-tracking.yml

L’exemple nginx limite les hôtes personnalisés aux ressources du tracker et aux routes d’ingestion. L’exemple Traefik utilise une entrée Host(...) exacte par nom d’hôte ; ne la remplacez pas par une règle générique, sauf si vous souhaitez accepter des noms arbitraires.

TLS à la demande avec Caddy

Ajoutez ces paramètres au service hitkeep :

HITKEEP_CUSTOM_TRACKING_TLS_MODE: caddy-on-demand
HITKEEP_CADDY_TLS_ASK_TOKEN: ${HITKEEP_CADDY_TLS_ASK_TOKEN:?set in .env}
# Optional. Use only when tracker hostnames point somewhere other than
# the host in HITKEEP_PUBLIC_URL.
HITKEEP_CUSTOM_TRACKING_DNS_TARGET: ${HITKEEP_CUSTOM_TRACKING_DNS_TARGET:-}

Générez le jeton dans votre terminal avec openssl rand -hex 32, puis ajoutez cette ligne à .env :

HITKEEP_CADDY_TLS_ASK_TOKEN=paste-the-generated-value-here

Utilisez un Caddyfile avec un stockage persistant et un point de vérification restreint :

{
email ops@example.com
storage file_system {
  root /data
}
on_demand_tls {
  ask http://hitkeep:8080/internal/caddy/on-demand-tls/{$HITKEEP_CADDY_TLS_ASK_TOKEN}
}
}

{$HITKEEP_HOSTNAME} {
reverse_proxy hitkeep:8080
encode zstd gzip
}

https:// {
tls {
  on_demand
}

reverse_proxy hitkeep:8080 {
  header_up Host {host}
  header_up X-Forwarded-Host {host}
  header_up X-Forwarded-Proto {scheme}
}

encode zstd gzip
}

Caddy envoie ?domain= à l’URL de vérification avant d’émettre un certificat. HitKeep renvoie 204 uniquement si le jeton correspond et si le nom demandé est un domaine de suivi actif dont le DNS a été vérifié. N’activez jamais le TLS à la demande sans ask, car tout nom d’hôte atteignant Caddy pourrait alors demander un certificat.

Le dépôt HitKeep propose un profil facultatif complet :

• examples/Caddyfile.custom-tracking
• examples/compose.caddy-on-demand.yml

Sauvegarder

Le démarrage rapide active le processus de sauvegarde cohérente de HitKeep et stocke les instantanés dans le volume persistant hitkeep_backups. Testez une restauration et copiez les sauvegardes hors de l’hôte Docker, afin qu’une panne ne détruise pas à la fois les données actives et celles de récupération. Consultez Sauvegarde et restauration pour l’ensemble complet des données et le processus de restauration.

Utiliser un stockage S3 compatible pour les sauvegardes ou les archives

Les exemples ci-dessus emploient des volumes Docker locaux. Pour écrire les instantanés ou les archives de rétention dans un stockage objet, remplacez les chemins locaux par des URL s3:// et ajoutez les paramètres S3 à .env :

# Local or S3 backup snapshots. Empty HITKEEP_BACKUP_PATH disables automatic backups.
HITKEEP_BACKUP_PATH=s3://my-analytics-bucket/hitkeep/backups
# Retention archives can use local paths or S3-compatible URLs.
HITKEEP_ARCHIVE_PATH=s3://my-analytics-bucket/hitkeep/archive
HITKEEP_S3_REGION=eu-central-1
# Static credentials are optional when your container runtime provides an AWS credential chain.
HITKEEP_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
HITKEEP_S3_SECRET_ACCESS_KEY=change-me

Pour MinIO, Cloudflare R2, Backblaze B2 ou un autre point de terminaison compatible S3, définissez également HITKEEP_S3_ENDPOINT et, si nécessaire, HITKEEP_S3_URL_STYLE=path. Consultez Sauvegardes S3 pour des exemples propres à chaque fournisseur.

Résolution des problèmes

Le tableau de bord affiche « An unexpected error occurred » pendant la configuration ou la connexion. Procédez dans cet ordre :

1. Lisez d’abord les journaux du conteneur avec docker compose logs hitkeep. HitKeep journalise chaque erreur serveur au niveau error. Si le navigateur affiche une erreur mais que les journaux restent silencieux, la requête n’a pas atteint le conteneur : vérifiez le proxy inverse ou HITKEEP_PUBLIC_URL.
2. HITKEEP_PUBLIC_URL doit correspondre exactement à la barre d’adresse, schéma, hôte et port compris. Avec une URL publique en https://, les cookies de session sont sécurisés et la connexion en HTTP échoue silencieusement. Après avoir modifié .env, relancez docker compose up -d : Compose n’applique l’environnement qu’en recréant le conteneur.
3. Setup has already been completed. indique qu’un utilisateur existe déjà, souvent dans un volume hitkeep_data d’un essai précédent. docker compose down -v supprime les volumes nommés et repart de zéro, mais efface toutes les données d’analyse.
4. La messagerie ne bloque pas la configuration initiale. La création du premier compte n’envoie aucun message ; des valeurs HITKEEP_MAIL_* vides ne l’empêchent jamais. SMTP n’intervient qu’ensuite pour les invitations, la réinitialisation des mots de passe et les rapports.
5. Besoin de plus de détails ? Ajoutez HITKEEP_LOG_LEVEL: debug sous environment: dans compose.yml, puis relancez docker compose up -d.

Ressources associées

• Proxys de confiance
• Connexion sociale
• Domaines de suivi personnalisés
• Référence de configuration
• Conservation des données
• Sauvegardes S3
• Installation binaire

Vous recherchez un hébergement géré avec un choix explicite de région ? Comparez HitKeep Cloud : HitKeep est exploité dans la région gérée de votre choix, UE (Francfort) ou États-Unis (Virginie).