---
title: "Executar o HitKeep como um único binário Linux | HitKeep"
description: "Execute o HitKeep como análise self-hosted de binário único em Linux físico, máquinas virtuais, Raspberry Pi ou redes restritas."
canonical: "https://hitkeep.com/pt/guides/installation/binary/"
---

# 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](https://hitkeep.com/reference/facts-and-limits/) 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](https://hitkeep.com/pt/guides/installation/docker-compose/). Se não quiser administrar servidores, atualizações, SMTP ou backups, use o [HitKeep Cloud](https://hitkeep.com/pt/pricing/).

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](https://hitkeep.com/pt/guides/installation/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](https://github.com/pascalebeier/hitkeep/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](https://hitkeep.com/reference/configuration/) 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](https://github.com/PascaleBeier/hitkeep/releases/latest) 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](https://hitkeep.com/guides/data/backups-and-restore/) para comandos de restauração e opções do S3.

## Relacionados

- [Proxies confiáveis](https://hitkeep.com/guides/installation/trusted-proxies/) — obrigatório ao executar atrás de um proxy reverso
- [Referência de configuração](https://hitkeep.com/reference/configuration/)
- [Fatos e limites](https://hitkeep.com/reference/facts-and-limits/)
- [Retenção de dados](https://hitkeep.com/guides/data/retention/)

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

[Anterior Homebrew](https://hitkeep.com/pt/guides/installation/homebrew/)[Próximo Docker Compose](https://hitkeep.com/pt/guides/installation/docker-compose/)