Skip to content
Start In Cloud

Binary Installation

HitKeep ships as a single Linux binary (~80 MB on amd64, slightly smaller on ARM). Download it, run it — that’s the entire deployment.

This makes the binary installation the right choice for:

  • Bare metal servers and VMs
  • Air-gapped or restricted-network environments
  • Raspberry Pi and ARM servers (AWS Graviton, Hetzner CAX)
  • Organizations that require the smallest possible attack surface

Download the latest release for your architecture from GitHub Releases:

Terminal window
# 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

For air-gapped environments: download the binary on an internet-connected machine, verify the SHA256 checksum from the GitHub release page, then transfer it to the target server.

For production Linux servers, use systemd to ensure HitKeep starts on boot and restarts on failure.

1. Create a dedicated service user and data directory:

Terminal window
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. Create /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)
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=/var/lib/hitkeep/data/hitkeep.db \
-archive-path=/var/lib/hitkeep/archive \
-http=:8080
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target

Or use a drop-in environment file for secrets (more secure — keeps secrets out of the unit file):

Terminal window
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. Enable and start:

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

Startup fails with failed to get final advertise address

Section titled “Startup fails with failed to get final advertise address”

If HitKeep exits immediately with:

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

the embedded cluster layer could not determine which IP address to advertise for gossip traffic. This usually happens in local or development environments where 0.0.0.0:7946 is used as the default bind address but the host does not have a discoverable private network address.

For a single-node local run, bind the cluster address explicitly to loopback:

Terminal window
./hitkeep -bind=127.0.0.1:7946

Or with an environment variable:

Terminal window
HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeep

For multi-node deployments, set -bind or HITKEEP_BIND_ADDR to a real private address reachable by the other nodes instead of loopback.

Single-team installs can operate from one hitkeep.db, but multiteam installs use the full data directory:

Terminal window
# Simple directory backup
cp -r /var/lib/hitkeep/data /backup/hitkeep-$(date +%Y%m%d)
# Or sync to remote storage
rclone copy /var/lib/hitkeep/data remote:my-bucket/hitkeep/

This captures the shared control plane database plus any tenant-local analytics databases under tenants/*/hitkeep.db.

Don’t want to manage systemd services, upgrades, and backups yourself? HitKeep Cloud → runs the binary in your chosen region (EU Frankfurt or US Virginia) with zero-downtime upgrades and automated backups.