High-performance, cookie-free, batteries-included server-side analytics.

Repo: github.com/hrodrig/kiko · Releases: Releases

Early development: kiko is in initial active development. Expect breaking changes, incomplete features, and data loss between releases. Do not use in production.

Privacy-first web analytics collector in Go. A ~500-byte tracking script sends inbound page views; the server hashes visitors without cookies, buffers hits in memory, and flushes sorted batch inserts plus hourly aggregations to SQLite (default), PostgreSQL, or MySQL.

This repo is kiko — collection only. kui (kiko + ui) is the analytics user interface in a separate repo: charts, tables, and reports over kiko's query API. kui is not built yet; the hero window on the right is where kui will sit.

Self-hosted deployment (Docker Compose, Helm, Kubernetes manifests): kiko-selfhosted — production paths and example stacks live there; this repo ships the application binary, packages, and container image only (same split as pgwd / pgwd-selfhosted).

GitHub repo traffic (history beyond 14 days): sibling tool gghstats — live stats for kiko (clone badge above).

Documentation: SPECIFICATIONS.md (architecture, schema, API), ROADMAP.md (phases), configs/kiko.yml.sample, and man kiko (when packaged).

Brand assets: hero banner assets/kiko-hero-full.png (compact assets/kiko-hero.png + source assets/kiko-hero.svg); favicons under assets/favicons/ (favicon.svg + PNG/ICO + manifest.json for future kui). The collector API does not serve these yet.

• Quick start
• Why kiko
• Design principles
• How it works
• Configuration
• Build & releases
• Tracking snippet
• API
  • Hit payload
• Quality gates
• Related
• Get involved
• Star History
• License

git clone https://github.com/hrodrig/kiko
cd kiko
make build
./kiko serve

Add to your site HTML (replace the host with your public kiko URL):

<script defer src="https://analytics.yourdomain.com/kiko.js"></script>

Custom config:

kiko serve -c /etc/kiko/kiko.yml

Probes for Kubernetes: GET /api/v1/healthz (liveness), GET /api/v1/readyz (readiness — DB + buffer). Deployment paths (Compose, Helm, MicroK8s): kiko-selfhosted.

↑ Back to top

• No cookies — SHA-256 visitor hash with daily salt. No GDPR banner needed.
• Batteries included — ~500B tracking script, in-memory buffer, batch flush, migrations, and health probes in one static binary.
• No Node in production — tracking script is ~500 bytes JS. Server is a static Go binary.
• Passes audits — govulncheck, grype, gocyclo, cover. Same standard as sibling projects.
• Single binary — Go, CGO disabled, distroless. ~2.5MB compiled.
• Multi-database — SQLite zero-config default; Postgres and MySQL via config.

↑ Back to top

The hero diagram is the product thesis in one glance: a Go collector built to do one job — gather web analytics on infrastructure you control, without turning visitors into tracking targets.

Light and fast. A ~500-byte tracking script feeds a compact Go binary tuned for throughput. Inbound hits are validated and hashed quickly; there is no heavyweight client SDK and no JavaScript runtime on the server — just a small static binary that chews through traffic like focused industrial gear.

Privacy by default. The whole pipeline sits inside a cookie-free boundary. Visitors become ephemeral daily hashes, not persistent profiles; IP addresses stay in memory and never reach disk. Measurement without surveillance — analytics you own, not cross-site fingerprinting.

Buffer, then batch. Hits accumulate in a visible in-memory buffer first. On a fixed interval they are sorted, aggregated, and flushed as organized batch inserts plus hourly rollups — the ordered blocks in the diagram. Hot path stays simple; database work stays predictable.

Your database, your choice. One collector, three backends: SQLite (zero-config default), PostgreSQL, or MySQL. Same schema and flush logic — pick the engine that fits your stack without forking the application.

That focus — fast ingestion, respectful privacy, smart batching, portable storage — is what kiko is for: a robust Go backend dedicated to collecting analytics sovereignly and respectfully. kui (kiko + ui) handles the UI in a separate project; kiko does not ship charts or admin screens.

↑ Back to top

The hero diagram maps this pipeline end to end: inbound raw data from the browser, buffered hits in the Go collector, sorted and aggregated batch writes, then SQLite / PostgreSQL / MySQL — read by kui (the UI, separate repo, future).

flowchart LR
    subgraph browser["Browser"]
        JS["kiko.js (~500B)"]
    end

    subgraph kiko["kiko (Go binary)"]
        direction TB
        IN["POST /api · GET /api.gif"]
        RL["rate limit (per IP)"]
        HASH["visitor_hash<br/>SHA-256(ip + ua + daily salt)"]
        BUF["MemBuffer<br/>(mutex, cap 4k)"]
        FLUSH["flush loop<br/>every 10s"]
        INSERT["BatchInserter + aggregations"]

        IN --> RL --> HASH --> BUF --> FLUSH --> INSERT
    end

    JS --> IN
    INSERT --> DB[("SQLite / PostgreSQL / MySQL")]
    DASH["kui (UI, separate repo)"] -.-> DB

Each hit is validated, hashed, and appended to an in-memory buffer (mutex-protected; drops when full). Every 10s the buffer flushes to the database in batch: raw hits, normalized paths/referrers, and hourly counts. Rate limiting uses a per-IP token bucket (pattern from gghstats).

↑ Back to top

Config file: kiko.yml (see configs/kiko.yml.sample). All fields overridable via env vars with KIKO_ prefix.

listen: ":8080"
public_url: "https://analytics.yourdomain.com"
log_level: info

database:
  driver: sqlite          # sqlite | postgres | mysql
  path: ./data/kiko.db    # sqlite only

buffer:
  flush_interval: 10      # seconds between batch flushes
  capacity: 4096          # max hits in memory before drop

rate_limit:
  enabled: true
  requests_per_sec: 100
  burst: 200
  host_requests_per_sec: 50   # optional per-host ingest cap
  host_burst: 100

filter:
  trust_proxy: false          # use first public IP from X-Forwarded-For / X-Real-IP
  block_bots: true
  block_prefetch: true
  block_referrer_spam: true
  block_datacenter_ips: false
  ignore_ips: []              # never count these client IPs
  extra_datacenter_cidrs: []

allowed_hosts: []         # empty = accept all

visitor:
  salt: ""                # set in production (KIKO_VISITOR_SALT)

↑ Back to top

Development (this repo):

make build
sudo cp kiko /usr/local/bin/   # optional

Production deployment (Compose, Helm, Kubernetes, env layout): kiko-selfhosted — not this repo.

Published artifacts: GitHub Releases and ghcr.io/hrodrig/kiko (multi-arch). Formats below are built by CI/Goreleaser from this repo; runbooks live in kiko-selfhosted.

↑ Back to top

The server embeds kiko.js (~500B). It sends POST /api via navigator.sendBeacon() and falls back to a 1×1 GIF pixel (GET /api.gif) when needed. Always responds with a transparent GIF — success and rejection look the same to the browser.

SPAs: pageviews fire on history.pushState / popstate (History API). For hash-based routers, load with ?hash=1 to also track hashchange.

The full tracking script source is open for audit at internal/server/kiko.js.

Never point the tracking script directly at your kiko domain — ad blockers and CSP policies will block it. Serve kiko.js and the API endpoints from your own domain via a reverse proxy (nginx, Traefik, Caddy, Cloudflare, etc.).

Set data-endpoint (or let kiko.js auto-detect) to match your proxy path:

<script defer
        src="https://your-domain.com/kiko/kiko.js"
        data-endpoint="https://your-domain.com/kiko"
        id="kiko-tracker">
</script>

The proxy must forward /kiko/kiko.js, /kiko/api, and /kiko/api.gif to the kiko backend, preserving the client IP via X-Forwarded-For.

Full walkthrough with examples (nginx, Traefik, multi-environment): kiko-selfhosted → Behind a reverse proxy.

↑ Back to top

All stats endpoints accept:

Auth: set api.key / KIKO_API_KEY. Send X-API-Key: <key> or Authorization: Bearer <key>. Empty key = open (dev only; server logs a warning).

Example

curl -sS 'http://127.0.0.1:8080/api/v1/stats/summary?host=gghstats.com&since=2026-01-01' \
  -H 'X-API-Key: your-secret'

Responses are JSON with Cache-Control: public, max-age=60.

The browser sends only the fields below. kiko enriches each hit server-side (visitor hash, browser/OS, traffic channel) before buffering — those are not part of the client JSON.

Headers

JSON body

Example

{
  "host": "gghstats.com",
  "path": "/blog/my-post",
  "referrer": "https://dev.to/someone",
  "title": "My Post | GGHStats",
  "width": 1920
}

Try it

curl -sS -X POST 'http://127.0.0.1:8080/api' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) Chrome/120.0.0.0' \
  -d '{"host":"localhost","path":"/demo","referrer":"https://google.com/search?q=kiko","title":"Demo","width":1920}' \
  -o /dev/null -w '%{http_code} %{content_type}\n'

Expect 200 image/gif (43-byte transparent GIF). Invalid or rejected hits return the same GIF so browsers cannot distinguish success from drop.

Response headers (ingest debugging):

Use debug mode behind a reverse proxy to verify client IP forwarding without polluting stats — see kiko-selfhosted for Traefik/Ingress examples.

Pixel fallback when sendBeacon is unavailable. Query params map to the same JSON fields:

Example

GET /api.gif?h=gghstats.com&p=%2Fblog%2Fmy-post&r=https%3A%2F%2Fdev.to%2Fsomeone&t=My%20Post&w=1920

Same User-Agent and client IP rules as POST /api.

Full API reference: SPECIFICATIONS.md §4.

↑ Back to top

Local check: make release-check

↑ Back to top

↑ Back to top

Found kiko useful? You can:

• Report bugs or suggest features — open an issue
• Contribute code — see CONTRIBUTING.md
• Star the repo — it helps others discover kiko

↑ Back to top

↑ Back to top

MIT — LICENSE

↑ Back to top