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
Section titled “Download”Download the latest release for your architecture from 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/hitkeepFor 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.
Running with Systemd
Section titled “Running with Systemd”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:
sudo useradd -r -s /bin/false hitkeepsudo mkdir -p /var/lib/hitkeep/data /var/lib/hitkeep/archivesudo chown -R hitkeep:hitkeep /var/lib/hitkeep2. Create /etc/systemd/system/hitkeep.service:
[Unit]Description=HitKeep AnalyticsAfter=network.target
[Service]Type=simpleUser=hitkeepGroup=hitkeepWorkingDirectory=/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 flagsExecStart=/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-failureRestartSec=5s
[Install]WantedBy=multi-user.targetOr use a drop-in environment file for secrets (more secure — keeps secrets out of the unit file):
sudo mkdir -p /etc/systemd/system/hitkeep.service.dsudo tee /etc/systemd/system/hitkeep.service.d/secrets.conf << 'EOF'[Service]Environment="HITKEEP_JWT_SECRET=your-secret-here"EOFsudo chmod 600 /etc/systemd/system/hitkeep.service.d/secrets.conf3. Enable and start:
sudo systemctl daemon-reloadsudo systemctl enable --now hitkeepsudo systemctl status hitkeepTroubleshooting
Section titled “Troubleshooting”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 providedthe 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:
./hitkeep -bind=127.0.0.1:7946Or with an environment variable:
HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeepFor multi-node deployments, set -bind or HITKEEP_BIND_ADDR to a real private address reachable by the other nodes instead of loopback.
Backup
Section titled “Backup”Single-team installs can operate from one hitkeep.db, but multiteam installs use the full data directory:
# Simple directory backupcp -r /var/lib/hitkeep/data /backup/hitkeep-$(date +%Y%m%d)
# Or sync to remote storagerclone 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.
Related
Section titled “Related”- Trusted Proxies — required if running behind a reverse proxy
- Configuration Reference
- Data Retention
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.