Ejecutar HitKeep como un único binario en Linux

La instalación mediante binario es la opción autogestionada más pequeña de HitKeep: un ejecutable para Linux, DuckDB y NSQ integrados y ninguna base de datos, caché ni cola externa. Úsala cuando necesites analítica web en un VPS con pocos recursos, una máquina virtual, una Raspberry Pi, un servidor físico o una red restringida donde Docker no sea la opción adecuada.

HitKeep publica binarios de cada versión únicamente para servidores Linux: linux/amd64 y linux/arm64. Descarga el archivo correspondiente, hazlo ejecutable y ejecútalo.

Consulta Datos y límites para citar el tamaño del binario, el uso de memoria, los límites de almacenamiento, los formatos de exportación y lo que HitKeep no pretende resolver. Los binarios actuales para Linux ocupan alrededor de 100 MB.

Docker Compose es más sencillo para la primera instalación

Si prefieres redes preparadas y volúmenes persistentes en lugar de administrar una unidad systemd, usa la configuración con Docker Compose. Si no quieres administrar servidores, actualizaciones, SMTP ni copias de seguridad, usa HitKeep Cloud.

Compatibilidad con Linux

Los binarios publicados para Linux se compilan en Ubuntu 22.04 y requieren glibc 2.35+. Se prueban en:

• Ubuntu 22.04 o posterior
• Debian 12 o posterior
• Amazon Linux 2023
• otras distribuciones basadas en glibc con glibc 2.35+

Si tu servidor usa una glibc anterior (por ejemplo, Ubuntu 20.04, Debian 11 o Amazon Linux 2), utiliza la configuración con Docker Compose.

Objetivos de compilación compatibles

Artefacto	Objetivo
hitkeep-linux-amd64	Servidores y máquinas virtuales Linux de 64 bits
hitkeep-linux-arm64	Servidores Linux ARM64, Raspberry Pi, AWS Graviton y Hetzner CAX
Imagen Docker	linux/amd64 y linux/arm64

Los binarios sin empaquetar están pensados para hosts Linux con una glibc moderna. Usa Docker Compose cuando necesites la imagen de contenedor o cuando la distribución del host sea anterior a la versión base del binario.

Por tanto, la instalación mediante binario es adecuada para:

• Servidores físicos y máquinas virtuales
• Entornos con redes restringidas
• Raspberry Pi y servidores ARM (AWS Graviton, Hetzner CAX)
• Organizaciones que necesitan la menor superficie de ataque posible

Inicio rápido

Descargar el binario

Descarga desde GitHub Releases la última versión para tu arquitectura:

# Linux AMD64 (most common VPS/server)
curl -L https://github.com/pascalebeier/hitkeep/releases/latest/download/hitkeep-linux-amd64 \
  -o hitkeep && chmod +x hitkeep && sudo mv hitkeep /usr/local/bin/hitkeep

# Linux ARM64 (Raspberry Pi, AWS Graviton, Hetzner CAX)
curl -L https://github.com/pascalebeier/hitkeep/releases/latest/download/hitkeep-linux-arm64 \
  -o hitkeep && chmod +x hitkeep && sudo mv hitkeep /usr/local/bin/hitkeep

En redes restringidas, descarga el binario y SHA256SUMS desde la página de la versión de GitHub en una máquina conectada a Internet, verifica la suma de comprobación y transfiere después el binario verificado al servidor de destino.

Ejecutar con systemd

En servidores Linux de producción, usa systemd para que HitKeep se inicie al arrancar y se reinicie si falla.

No expongas secretos en la lista de procesos

Nunca pases HITKEEP_JWT_SECRET ni contraseñas SMTP como flags de línea de comandos: cualquier usuario puede verlas mediante ps aux. Usa variables de entorno o un archivo de entorno adicional.

Cada flag tiene una variable de entorno HITKEEP_* equivalente en una relación 1:1 (--public-url ↔ HITKEEP_PUBLIC_URL). Por tanto, puedes configurar todo mediante el entorno si lo prefieres. La unidad siguiente mezcla ambos métodos únicamente para que los secretos no aparezcan en la línea de comandos. La referencia de configuración enumera ambas formas para cada opción.

1. Crea un usuario de servicio y un directorio de datos específicos:

sudo useradd -r -s /bin/false hitkeep
sudo mkdir -p /var/lib/hitkeep/data /var/lib/hitkeep/archive
sudo chown -R hitkeep:hitkeep /var/lib/hitkeep

2. Crea /etc/systemd/system/hitkeep.service:

[Unit]
Description=HitKeep Analytics
After=network.target

[Service]
Type=simple
User=hitkeep
Group=hitkeep
WorkingDirectory=/var/lib/hitkeep

# Sensitive values via environment (not visible in ps aux).
# Generate the secret with: openssl rand -hex 32
Environment="HITKEEP_JWT_SECRET=change-this-to-a-long-random-string"
Environment="HITKEEP_MAIL_PASSWORD=your-smtp-password"

# General configuration via flags
ExecStart=/usr/local/bin/hitkeep \
  --public-url=https://analytics.example.com \
  --db-path=/var/lib/hitkeep/data/hitkeep.db \
  --data-path=/var/lib/hitkeep/data \
  --archive-path=/var/lib/hitkeep/archive \
  --http-addr=:8080

Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

También puedes usar un archivo de entorno adicional para los secretos, una opción más segura que evita guardarlos en la unidad:

sudo mkdir -p /etc/systemd/system/hitkeep.service.d
sudo tee /etc/systemd/system/hitkeep.service.d/secrets.conf << 'EOF'
[Service]
Environment="HITKEEP_JWT_SECRET=your-secret-here"
EOF
sudo chmod 600 /etc/systemd/system/hitkeep.service.d/secrets.conf

3. Activa e inicia el servicio:

sudo systemctl daemon-reload
sudo systemctl enable --now hitkeep
sudo systemctl status hitkeep

Verificación

Confirma la versión instalada, el estado del servicio y la disponibilidad de la base de datos:

hitkeep --version
sudo systemctl --no-pager status hitkeep
curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/readyz

/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.

Publicar HitKeep en un subdirectorio

La mayoría de instalaciones deberían usar un hostname dedicado, como https://analytics.example.com. Si necesitas publicar HitKeep debajo de otro sitio, define HITKEEP_PUBLIC_URL con la ruta externa completa:

Environment="HITKEEP_PUBLIC_URL=https://www.example.net/hitkeep/"

o bien:

hitkeep --public-url=https://www.example.net/hitkeep/

El proxy inverso debe reenviar el mismo prefijo de ruta a HitKeep sin eliminarlo mediante una reescritura:

www.example.net {
  handle /hitkeep* {
    reverse_proxy 127.0.0.1:8080
  }
}

Cuando la URL pública contiene /hitkeep/, el panel inserta <base href="/hitkeep/" />, las llamadas a la API permanecen bajo /hitkeep/api/... y el fragmento del tracker se puede instalar así:

<script async src="https://www.example.net/hitkeep/hk.js"></script>

Si Web Vitals está activado, hk.js carga https://www.example.net/hitkeep/hk-vitals.js y envía muestras a /hitkeep/ingest/web-vitals. Las páginas vistas y los eventos automáticos siguen la misma regla para /hitkeep/ingest y /hitkeep/ingest/event.

En el modo con prefijo de ruta, HitKeep no expone rutas raíz /api/..., /hk.js ni rutas alternativas del panel. Los endpoints locales /healthz y /readyz siguen disponibles para comprobaciones de procesos, contenedores y Kubernetes.

Solución de problemas

El inicio falla con failed to get final advertise address

Si HitKeep termina inmediatamente con:

failed to get final advertise address: no private IP address found, and explicit IP not provided

la capa de clúster integrada no ha podido determinar qué dirección IP anunciar para el tráfico gossip. Esto suele ocurrir en entornos locales o de desarrollo donde se usa 0.0.0.0:7946 como dirección de enlace predeterminada, pero el host no tiene una dirección de red privada detectable.

Para una ejecución local de un único nodo, enlaza de forma explícita la dirección del clúster al loopback:

./hitkeep --bind-addr=127.0.0.1:7946

O mediante una variable de entorno:

HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeep

En despliegues multinodo, define --bind-addr o HITKEEP_BIND_ADDR con una dirección privada real accesible desde los demás nodos, no con el loopback.

Actualización

Lee las notas de la última versión y crea una copia de seguridad completa. Descarga el binario nuevo para la misma arquitectura con el comando del inicio rápido y sustituye el ejecutable mientras el servicio está detenido:

sudo systemctl stop hitkeep
sudo install -m 0755 ./hitkeep /usr/local/bin/hitkeep
sudo systemctl start hitkeep
curl --fail http://127.0.0.1:8080/readyz
hitkeep --version

Conserva el binario anterior y la copia previa a la actualización hasta que tanto la comprobación de disponibilidad como una solicitud de seguimiento funcionen. Revisa las notas de la versión antes de volver a una versión anterior; una versión con migraciones de datos puede impedir ejecutar un binario anterior sobre los datos actualizados.

Copias de seguridad

Para un servicio en ejecución, usa preferentemente el worker integrado de copias de seguridad con checkpoints de HitKeep. Añade estas entradas a la sección [Service] de la unidad o a un archivo adicional de systemd y reinicia el servicio:

Environment="HITKEEP_BACKUP_PATH=/var/lib/hitkeep/backups"
Environment="HITKEEP_BACKUP_INTERVAL=60"
Environment="HITKEEP_BACKUP_RETENTION=24"

Para copiar directamente el sistema de archivos, detén primero HitKeep para evitar que la base de datos y el WAL cambien por separado:

sudo systemctl stop hitkeep
rsync -a /var/lib/hitkeep/data/ /backup/hitkeep-$(date +%Y%m%d)/
rsync -a /var/lib/hitkeep/archive/ /backup/hitkeep-archive-$(date +%Y%m%d)/
sudo systemctl start hitkeep

La copia debe incluir el HITKEEP_DB_PATH configurado, todo el árbol HITKEEP_DATA_PATH con las bases de datos de los tenants en tenants/*/hitkeep.db y cualquier ruta de archivos que necesites conservar. Consulta Copias de seguridad y restauración para ver comandos de restauración y opciones de S3.

Contenido relacionado

• Proxies de confianza — obligatorio si ejecutas HitKeep detrás de un proxy inverso
• Referencia de configuración
• Datos y límites
• Retención de datos

¿No quieres administrar servicios systemd, actualizaciones y copias de seguridad? Compara HitKeep Cloud.