Autogestionar HitKeep con Docker Compose

Docker Compose permite un despliegue reproducible y controlado por versiones con volúmenes de almacenamiento persistente. Tus datos de analítica permanecen en un volumen Docker con nombre dentro de tu servidor, incluidos el archivo compartido hitkeep.db y las bases de datos locales de cada tenant creadas bajo tenants/*/hitkeep.db.

Esta página explica cómo ejecutar HitKeep como servicio autogestionado. Si buscas el entorno para colaboradores con recarga en caliente, Go, Air, Angular, Mailpit y datos de demostración en Docker, consulta la guía para contribuir.

En cada versión, las imágenes de HitKeep se publican en dos registros:

Registro	Imagen
Docker Hub	pascalebeier/hitkeep
GitHub Container Registry	ghcr.io/pascalebeier/hitkeep

Ambos registros contienen imágenes multiplataforma idénticas (linux/amd64, linux/arm64) con declaraciones de procedencia firmadas. Usa el registro que mejor se adapte a tu red o a tus límites de descargas.

No guardes secretos en los archivos de Compose

Pasa los valores sensibles (HITKEEP_JWT_SECRET, contraseñas SMTP) mediante variables de entorno, un archivo .env o secretos de Docker, no incrustados en compose.yml ni en flags de comandos. Excluye .env del control de versiones. Para una gestión más estricta, usa secretos de Docker.

Inicio rápido

Un despliegue consta de dos archivos en el mismo directorio: compose.yml (cópialo literalmente; no tendrás que editarlo) y .env (aquí defines tus valores). Al iniciar, Compose sustituye cada ${VARIABLE} de compose.yml por la línea correspondiente de .env.

1. Crear compose.yml

Crea un directorio y añade este compose.yml. Esta configuración base conserva los datos activos, los archivos de retención y las instantáneas automáticas de respaldo en volúmenes con nombres separados. El mismo archivo se mantiene en el repositorio como examples/compose.yml, junto con examples/.env.example, por si prefieres copiarlo desde el código fuente.

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. Crear .env

Genera primero la clave de firma de sesiones. Ejecuta este comando en la terminal y copia el resultado:

openssl rand -hex 32

Si no tienes openssl, head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n'; echo produce un valor equivalente en cualquier máquina Linux.

Crea después un archivo llamado .env junto a compose.yml, ábrelo con tu editor y completa tus valores:

# 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 no es un script del shell

.env contiene líneas sencillas con el formato KEY=value: sin echo, sin llaves y sin sustituciones $(command). Docker Compose lo lee literalmente, por lo que cualquier comando pegado en el archivo se convierte en texto literal. No es necesario entrecomillar los valores. Excluye el archivo del control de versiones añadiéndolo a .gitignore.

Los dos archivos usan sintaxis distintas de forma intencionada: compose.yml es YAML, así que sus entradas de entorno tienen el formato KEY: value; .env usa el formato dotenv, KEY=value.

3. Iniciar HitKeep

docker compose up -d
docker compose logs -f hitkeep

Las líneas de registro Starting HitKeep y HTTP server starting indican que el servicio está activo.

4. Iniciar sesión

Abre HITKEEP_PUBLIC_URL en el navegador. El asistente crea la primera cuenta, que se convierte automáticamente en propietaria de la instancia, y te guía para añadir tu primer sitio.

El archivo de base de datos reside en el volumen hitkeep_data. Por tanto, el directorio de recuperación automática predeterminado, /var/lib/hitkeep/data/recovery, también es persistente. Los archivos de retención se guardan en hitkeep_archive y las instantáneas automáticas de la base de datos en hitkeep_backups. Los paquetes de recuperación contienen material de la base de datos, no se rotan con la retención de copias y deben protegerse y eliminarse por separado. MCP se publica en /mcp, pero los clientes siguen necesitando tokens bearer de clientes API con el alcance adecuado.

MCP es opcional en el producto y está activado en este ejemplo de Compose para equipos que quieran acceso de solo lectura desde asistentes o herramientas de informes. Elimina HITKEEP_MCP_ENABLED, HITKEEP_MCP_PATH y HITKEEP_MCP_MAX_RANGE_DAYS si no vas a publicar un endpoint MCP.

El enriquecimiento mediante proveedores de IA es opcional y está desactivado de forma predeterminada. Mantén HITKEEP_AI_ENABLED=false hasta elegir un proveedor y un modelo, configurar las credenciales y definir límites de presupuesto locales. Consulta Recomendaciones de oportunidades y la guía de configuración de modelos de IA para conocer los campos exactos.

El inicio de sesión social es opcional. Define el ID y el secreto de cliente de cada proveedor que quieras mostrar en HitKeep y registra después la URL de callback exacta derivada de HITKEEP_PUBLIC_URL. La guía de inicio de sesión social explica el registro de proveedores, las rutas de callback, la verificación del correo, las invitaciones, MFA y la vinculación de cuentas. HITKEEP_SOCIAL_SIGNUP_ENABLED no habilita el registro público en una instancia autogestionada.

Los datos de consulta de ciudad, proveedor y ASN están integrados en las imágenes de cada versión. Los despliegues con Compose no necesitan IP2LOCATION_DOWNLOAD_TOKEN durante la ejecución.

Verificación

Confirma que Compose muestra un servicio en ejecución y que ambos endpoints responden correctamente:

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

/healthz confirma que el proceso está activo. /readyz confirma que la base de datos compartida y todas las bases de datos de tenants abiertas están listas. Si HitKeep solo es accesible a través del proxy inverso, comprueba en su lugar la URL visible en el navegador.

Actualización

Lee las notas de la última versión y confirma que existe una copia de seguridad actual. Descarga después la imagen estable vigente y vuelve a crear únicamente el servicio HitKeep:

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

Compose conserva los volúmenes con nombre para datos, archivos y copias cuando reemplaza el contenedor. No ejecutes docker compose down -v durante una actualización: -v elimina esos volúmenes.

Configuraciones de proxy inverso

Ejecuta HitKeep detrás de un proxy inverso para ofrecer HTTPS en producción. Configura los proxies de confianza para usar las IP reales de los clientes en la analítica y los límites de solicitudes.

HITKEEP_PUBLIC_URL puede incluir un prefijo de ruta. Por ejemplo, define HITKEEP_PUBLIC_URL=https://www.example.net/hitkeep/ si HitKeep se publica debajo de un sitio existente. El proxy debe exponer el mismo prefijo, como /hitkeep/*, y reenviarlo al contenedor de HitKeep. HitKeep servirá entonces bajo ese prefijo el base href del panel, las solicitudes de API, hk.js, hk-vitals.js y los endpoints de ingestión.

Caddy

caddy-docker-proxy gestiona HTTPS automático (Let’s Encrypt) y genera la configuración de Caddy directamente a partir de etiquetas de Docker. La práctica recomendada es usar una red de entrada específica y confiar únicamente en el CIDR de esa red en 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

Hay que obtener dos valores desde la terminal: el secreto de sesión y el CIDR de la red de Caddy:

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

Crea después el archivo .env con tu editor:

# 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 debe ser el CIDR de la red del proxy inverso, no 0.0.0.0/0.

Para publicar en un subdirectorio, mantén alineados HITKEEP_PUBLIC_URL y el prefijo de ruta del proxy inverso. La ruta equivalente de Caddy es:

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

Para un nginx existente en el host, que administre sus propios certificados, por ejemplo mediante certbot, conserva el compose.yml del inicio rápido y dirige nginx al puerto publicado.

Aplica dos cambios a los archivos del inicio rápido:

1. En compose.yml, enlaza el puerto al loopback para que solo el nginx local pueda llegar al contenedor:

    ports:
    - "127.0.0.1:8080:8080"

2. En .env, define la URL pública con el dominio servido por nginx y confía en la red Docker. El tráfico del host llega al contenedor mediante la puerta de enlace de la red Docker, situada en el intervalo 172.16.0.0/12:

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

Añade después un bloque de servidor a 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;
  }
}

Recarga nginx (nginx -t && systemctl reload nginx) y abre https://analytics.example.com. Si todos los visitantes parecen proceder de una única IP privada, revisa los proxies de confianza.

Traefik

En stacks existentes de Traefik, publica HitKeep mediante etiquetas:

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: {}

Dominios de seguimiento personalizados

Los equipos que autogestionan HitKeep pueden usar dominios de seguimiento personalizados con cualquier proxy inverso que termine TLS y conserve el encabezado Host original. Usa el modo TLS externo cuando nginx, Traefik, un balanceador de carga u otro proceso ACME administren los certificados. Usa el perfil de Caddy solo si quieres incorporar dominios desde el panel con emisión de certificados bajo demanda.

TLS externo con nginx o Traefik

Añade esta configuración de HitKeep cuando el proxy inverso ya gestione los certificados:

HITKEEP_CUSTOM_TRACKING_TLS_MODE: external

En el modo externo, añade cada hostname de seguimiento al proxy antes de que el equipo pulse Verificar en HitKeep. La comprobación requiere que https://<hostname>/hk.js devuelva el tracker con un certificado válido.

El repositorio de HitKeep incluye ejemplos sin Caddy:

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

El ejemplo de nginx limita los hosts de seguimiento personalizados a los recursos del tracker y las rutas de ingestión en el proxy. El ejemplo de Traefik usa entradas Host(...) exactas para cada hostname; no las sustituyas por una regla comodín salvo que quieras aceptar deliberadamente hostnames arbitrarios.

TLS bajo demanda de Caddy

Añade esta configuración al servicio 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:-}

Genera el token de consulta en la terminal (openssl rand -hex 32) y añádelo como una línea nueva a .env:

HITKEEP_CADDY_TLS_ASK_TOKEN=paste-the-generated-value-here

Usa un Caddyfile con almacenamiento persistente y un endpoint de consulta TLS bajo demanda restringido:

{
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 envía ?domain= a la URL de consulta antes de emitir un certificado. HitKeep responde con 204 únicamente si el token coincide y el hostname solicitado pertenece a un dominio de seguimiento personalizado activado y verificado mediante DNS. No ejecutes TLS bajo demanda de Caddy sin ask: cualquier hostname que alcance el listener de Caddy podría intentar emitir un certificado.

El repositorio de HitKeep incluye un perfil opcional completo:

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

Copias de seguridad

El inicio rápido activa el worker de copias con checkpoints de HitKeep y guarda las instantáneas en el volumen persistente hitkeep_backups. Prueba una restauración antes de depender de ellas y copia los respaldos fuera del host Docker para que un fallo del host no elimine a la vez los datos activos y los de recuperación. Consulta Copias de seguridad y restauración para conocer el conjunto completo de datos y el proceso de restauración.

Usar copias de seguridad o archivos compatibles con S3

Los ejemplos anteriores usan volúmenes Docker locales. Para escribir instantáneas de respaldo o archivos de retención en almacenamiento de objetos, sustituye las rutas locales por URL s3:// y añade la configuración S3 a .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

Para MinIO, Cloudflare R2, Backblaze B2 u otro endpoint compatible con S3, define también HITKEEP_S3_ENDPOINT y, cuando sea necesario, HITKEEP_S3_URL_STYLE=path. Consulta Copias de seguridad en S3 para ver ejemplos específicos de cada proveedor.

Solución de problemas

El panel muestra “An unexpected error occurred” durante la configuración o el inicio de sesión. Revisa estos puntos en orden:

1. Lee primero los registros del contenedor: docker compose logs hitkeep. HitKeep registra cada fallo del servidor con nivel de error. Si el navegador muestra un error pero los registros permanecen vacíos, la solicitud no ha alcanzado el contenedor; esto apunta al proxy inverso o a un HITKEEP_PUBLIC_URL incorrecto, no a HitKeep.
2. HITKEEP_PUBLIC_URL debe coincidir exactamente con la barra de direcciones: esquema, host y puerto. Con una URL pública https://, las cookies de sesión se marcan como seguras y el inicio de sesión mediante HTTP sin cifrar falla de forma silenciosa. Después de cambiar .env, vuelve a ejecutar docker compose up -d; Compose solo aplica los cambios de entorno al recrear el contenedor.
3. Setup has already been completed. significa que ya existe un usuario en la base de datos, normalmente en un volumen hitkeep_data de un intento anterior. docker compose down -v elimina los volúmenes con nombre y permite empezar de cero; esta acción borra todos los datos de analítica.
4. La configuración del correo no provoca fallos durante la configuración inicial. Crear la primera cuenta no envía correo; los valores HITKEEP_MAIL_* vacíos nunca la bloquean. SMTP solo interviene después para invitaciones, restablecimientos de contraseña e informes por correo.
5. ¿Necesitas más detalle? Añade HITKEEP_LOG_LEVEL: debug bajo environment: en compose.yml y vuelve a ejecutar docker compose up -d.

Contenido relacionado

• Proxies de confianza
• Inicio de sesión social
• Dominios de seguimiento personalizados
• Referencia de configuración
• Retención de datos
• Copias de seguridad en S3
• Instalación mediante binario

¿Necesitas alojamiento administrado con elección explícita de región? Compara HitKeep Cloud.