Executar o HitKeep como um único binário Linux

A instalação pelo binário é a opção self-hosted mais enxuta do HitKeep: um executável Linux, DuckDB incorporado, NSQ incorporado e nenhum serviço externo de banco de dados, cache ou filas. Use-a para executar análise web em um VPS com poucos recursos, máquina virtual, Raspberry Pi, servidor físico ou rede restrita onde o Docker não seja a melhor opção.

O HitKeep publica binários brutos apenas para servidores Linux: linux/amd64 e linux/arm64. Baixe o arquivo correspondente, torne-o executável e execute-o.

Consulte Fatos e limites para obter dados citáveis sobre tamanho do binário, uso de memória, limites de armazenamento, formatos de exportação e o que não faz parte do produto. Os binários Linux atuais têm aproximadamente 100 MB.

Docker Compose é mais simples para a primeira instalação

Se você prefere rede pronta e volumes persistentes em vez de gerenciar uma unidade systemd, use a configuração com Docker Compose. Se não quiser administrar servidores, atualizações, SMTP ou backups, use o HitKeep Cloud.

Compatibilidade com Linux

Os binários Linux publicados são compilados no Ubuntu 22.04 e exigem glibc 2.35+. Eles são testados em:

• Ubuntu 22.04 ou mais recente
• Debian 12 ou mais recente
• Amazon Linux 2023
• outras distribuições baseadas em glibc com glibc 2.35+

Se o servidor usa uma glibc mais antiga (por exemplo, Ubuntu 20.04, Debian 11 ou Amazon Linux 2), use a configuração com Docker Compose.

Destinos de compilação compatíveis

Artefato	Destino
hitkeep-linux-amd64	Servidores e máquinas virtuais Linux de 64 bits
hitkeep-linux-arm64	Servidores Linux ARM64, Raspberry Pi, AWS Graviton e Hetzner CAX
Imagem Docker	linux/amd64 e linux/arm64

Os binários brutos destinam-se a hosts Linux com glibc moderna. Use Docker Compose quando precisar da imagem de contêiner ou quando a distribuição do host for anterior à base do binário.

A instalação pelo binário é indicada para:

• servidores físicos e máquinas virtuais;
• ambientes com rede restrita;
• Raspberry Pi e servidores ARM (AWS Graviton, Hetzner CAX);
• organizações que exigem a menor superfície de ataque possível.

Início rápido

Baixar o binário

Baixe a versão mais recente para sua arquitetura em GitHub Releases:

# 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

Em redes restritas, baixe o binário e SHA256SUMS da página da versão no GitHub em uma máquina conectada à internet, verifique o checksum e transfira o binário verificado para o servidor de destino.

Executar com systemd

Em servidores Linux de produção, use systemd para iniciar o HitKeep com o sistema e reiniciá-lo em caso de falha.

Não exponha segredos na lista de processos

Nunca passe HITKEEP_JWT_SECRET nem senhas SMTP como parâmetros de linha de comando: todos os usuários podem vê-los com ps aux. Use variáveis de ambiente ou um arquivo de ambiente drop-in.

Cada parâmetro tem uma variável de ambiente HITKEEP_* equivalente (--public-url ↔ HITKEEP_PUBLIC_URL), portanto toda a configuração pode ficar no ambiente. A unidade abaixo mistura as duas formas apenas para manter os segredos fora da linha de comando visível. A Referência de configuração lista as duas formas de cada opção.

1. Crie um usuário dedicado para o serviço e o diretório de dados:

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

Como alternativa, use um arquivo de ambiente drop-in para os segredos (mais seguro, pois eles não ficam no arquivo da unidade):

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. Ative e inicie:

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

Verificar

Confirme a versão instalada, o estado do serviço e a prontidão do banco de dados:

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 o processo está ativo. /readyz confirma que o banco compartilhado e todos os bancos de tenants abertos estão prontos.

Montar o HitKeep em um subdiretório

Na maioria das instalações, use um hostname dedicado, como https://analytics.example.com. Para publicar o HitKeep abaixo de outro site, defina HITKEEP_PUBLIC_URL com o caminho externo completo:

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

ou:

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

O proxy reverso deve encaminhar o mesmo prefixo para o HitKeep sem removê-lo:

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

Quando a URL pública contém /hitkeep/, o painel injeta <base href="/hitkeep/" />, as chamadas da API permanecem em /hitkeep/api/... e o snippet de rastreamento pode ser instalado assim:

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

Se Web Vitals estiver ativado, hk.js carrega https://www.example.net/hitkeep/hk-vitals.js e envia amostras a /hitkeep/ingest/web-vitals. Visualizações de página e eventos automáticos seguem a mesma regra para /hitkeep/ingest e /hitkeep/ingest/event.

No modo com prefixo, o HitKeep não expõe na raiz /api/..., /hk.js nem as rotas de fallback do painel. /healthz e /readyz continuam disponíveis localmente para verificações de processo, contêiner e Kubernetes.

Solução de problemas

A inicialização falha com failed to get final advertise address

Se o HitKeep encerra imediatamente com:

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

a camada de cluster incorporada não conseguiu determinar qual endereço IP deve anunciar para o tráfego gossip. Isso costuma ocorrer em ambientes locais ou de desenvolvimento quando 0.0.0.0:7946 é usado como endereço padrão, mas o host não tem um endereço de rede privada detectável.

Para uma execução local de nó único, vincule explicitamente o endereço do cluster ao loopback:

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

Ou com uma variável de ambiente:

HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeep

Em implantações com vários nós, defina --bind-addr ou HITKEEP_BIND_ADDR com um endereço privado real acessível aos outros nós, não o loopback.

Atualizar

Leia as notas da versão mais recente e faça um backup completo. Baixe o novo binário para a mesma arquitetura usando o comando do início rápido e substitua o executável enquanto o serviço estiver parado:

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

Mantenha o binário anterior e o backup pré-atualização até que a verificação de prontidão e uma requisição de rastreamento tenham sucesso. Leia as notas antes de reverter uma versão; versões com migrações de dados talvez não permitam executar um binário antigo sobre dados já atualizados.

Backup

Prefira o worker de backup com checkpoints do HitKeep para um serviço em execução. Adicione estas entradas à seção [Service] da unidade ou a um drop-in do systemd e reinicie o serviço:

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

Para uma cópia bruta do sistema de arquivos, pare primeiro o HitKeep para que banco e WAL não mudem separadamente:

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

A cópia deve incluir o HITKEEP_DB_PATH configurado, toda a árvore de HITKEEP_DATA_PATH com os bancos dos tenants em tenants/*/hitkeep.db e todo caminho de arquivos que você precise preservar. Consulte Backups e restauração para comandos de restauração e opções do S3.

Relacionados

• Proxies confiáveis — obrigatório ao executar atrás de um proxy reverso
• Referência de configuração
• Fatos e limites
• Retenção de dados

Não quer administrar serviços systemd, atualizações e backups? Compare o HitKeep Cloud para hospedagem gerenciada na UE (Frankfurt) ou nos EUA (Virgínia), com atualizações sem indisponibilidade e backups automáticos.