---
title: "Ejecutar HitKeep como un único binario en Linux | HitKeep"
description: "Ejecuta HitKeep como analítica autogestionada en un único binario sobre servidores físicos Linux, máquinas virtuales, Raspberry Pi o redes restringidas."
canonical: "https://hitkeep.com/es/guides/installation/binary/"
---

# 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](https://hitkeep.com/reference/facts-and-limits/) 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](https://hitkeep.com/es/guides/installation/docker-compose/). Si no quieres administrar servidores, actualizaciones, SMTP ni copias de seguridad, usa [HitKeep Cloud](https://hitkeep.com/es/pricing/).

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](https://hitkeep.com/es/guides/installation/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](https://github.com/pascalebeier/hitkeep/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](https://hitkeep.com/reference/configuration/) 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](https://github.com/PascaleBeier/hitkeep/releases/latest) 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](https://hitkeep.com/guides/data/backups-and-restore/) para ver comandos de restauración y opciones de S3.

## Contenido relacionado

- [Proxies de confianza](https://hitkeep.com/guides/installation/trusted-proxies/) — obligatorio si ejecutas HitKeep detrás de un proxy inverso
- [Referencia de configuración](https://hitkeep.com/reference/configuration/)
- [Datos y límites](https://hitkeep.com/reference/facts-and-limits/)
- [Retención de datos](https://hitkeep.com/guides/data/retention/)

¿No quieres administrar servicios systemd, actualizaciones y copias de seguridad? [Compara HitKeep Cloud](https://hitkeep.com/es/pricing/).

[Página anterior Homebrew](https://hitkeep.com/es/guides/installation/homebrew/)[Siguiente página Docker Compose](https://hitkeep.com/es/guides/installation/docker-compose/)