Binary Installation

HitKeep’s binary install is the smallest self-hosted path: one Linux executable, embedded DuckDB, embedded NSQ, and no external database, cache, or queue service. Use it when you want web analytics on a low-resource VPS, VM, Raspberry Pi, bare-metal server, or restricted network where Docker is not the right fit.

HitKeep publishes raw release binaries for Linux servers only: linux/amd64 and linux/arm64. Download the matching file, make it executable, and run it.

For citable binary size, memory use, storage boundaries, export formats, and non-goals, use Facts and Limits. Current Linux release binaries are about 100 MB.

Docker Compose is easier for first installs

If you want packaged networking and persistent volumes instead of managing a systemd unit yourself, use the Docker Compose setup. If you do not want to manage servers, upgrades, SMTP, or backups at all, use HitKeep Cloud.

Linux compatibility

The published Linux binaries are built on Ubuntu 22.04 and require glibc 2.35+. They are tested on:

• Ubuntu 22.04 or later
• Debian 12 or later
• Amazon Linux 2023
• other glibc-based distributions with glibc 2.35+

If your server runs an older glibc (e.g., Ubuntu 20.04, Debian 11, Amazon Linux 2), use the Docker Compose setup instead.

Supported Build Targets

Artifact	Target
hitkeep-linux-amd64	64-bit Linux servers and VMs
hitkeep-linux-arm64	ARM64 Linux servers, Raspberry Pi, AWS Graviton, Hetzner CAX
Docker image	linux/amd64 and linux/arm64

Raw binaries are intended for Linux hosts with a modern glibc. Use Docker Compose when you need the container image or when the host distribution is older than the binary baseline.

This makes the binary installation the right choice for:

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

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/hitkeep

For restricted networks: download the binary and SHA256SUMS from the GitHub release page on an internet-connected machine, verify the checksum, then transfer the verified binary to the target server.

Running with Systemd

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

Keep secrets out of process listings

Never pass HITKEEP_JWT_SECRET or SMTP passwords as command-line flags — they are visible to all users via ps aux. Use environment variables or a drop-in environment file instead.

1. Create a dedicated service user and data directory:

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-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

Or 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.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:

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

Mount HitKeep under a subdirectory

Most installs should use a dedicated analytics hostname such as https://analytics.example.com. If you need to publish HitKeep below another site, set HITKEEP_PUBLIC_URL to the full external path:

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

or:

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

The reverse proxy must forward the same path prefix to HitKeep without rewriting it away:

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

When the public URL contains /hitkeep/, the dashboard injects <base href="/hitkeep/" />, API calls stay under /hitkeep/api/..., and the tracker snippet can be installed as:

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

If Web Vitals are enabled, hk.js loads https://www.example.net/hitkeep/hk-vitals.js and sends samples to /hitkeep/ingest/web-vitals. Pageviews and automatic events follow the same rule for /hitkeep/ingest and /hitkeep/ingest/event.

In path-prefix mode, HitKeep does not expose root /api/..., /hk.js, or dashboard fallback routes. Local /healthz and /readyz remain available for process, container, and Kubernetes checks.

Troubleshooting

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:

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

Or with an environment variable:

HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeep

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

Backup

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

# 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.

Related

• Trusted Proxies — required if running behind a reverse proxy
• Configuration Reference
• Facts and Limits
• 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.