Documentation

Overview

Trackifly is a self-hosted traffic tracking system split into two services:

• Hub — the control plane: admin dashboard, API, configs, reporting, ClickHouse integration.
• Edge — the traffic plane: runs near your domains, serves landers, routes traffic, records events, streams back to Hub.

Both run as small Go binaries inside Docker containers. A Caddy reverse proxy handles HTTP/HTTPS and routes /api/*, /app/*, and / to the right service.

Requirements

• Linux VPS (Ubuntu 22.04+ or Debian 12+ recommended)
• Docker + Docker Compose plugin
• 2 GB RAM minimum (4 GB recommended for ClickHouse)
• Domain name pointed at the VPS (for HTTPS)

Quick start

1. 1
   Install Docker (if not already installed)

   curl -fsSL https://get.docker.com | sh
   systemctl enable docker

2. 2
   Run the Trackifly installer

   curl -fsSL https://trackifly.com/install.sh | bash

   The script will ask for your domain (or IP) and an admin password, then start everything. Takes ~3 minutes on a fresh VPS.

3. 3
   Open your dashboard

   https://<your-domain>/app/

   All containers should be Up. /api/healthz returns ok when Hub is ready.

Advanced / unattended install

curl -fsSL https://trackifly.com/install.sh | bash -s -- \
  --dir /opt/trackifly \
  --domain trackifly.example.com \
  --user admin \
  --pass <password>

All flags are optional — the script prompts interactively for anything not provided.

Environment variables

All config lives in deploy/.env (based on deploy/prod.env.example).

Required

HUB_JWT_SECRET=        # Random string, 32+ chars. Used to sign admin JWTs.
HUB_ADMIN_USER=admin   # Admin login username
HUB_ADMIN_PASS=        # Admin login password

Optional

HOST=:80               # Use :80 for IP-only. Set to domain.com for HTTPS.
HUB_STORE=redis        # "redis" (default) or "memory" for dev
REDIS_ADDR=redis:6379  # Redis address (used with HUB_STORE=redis)
CH_ADDR=clickhouse:9000 # ClickHouse address for analytics
EDGE_NODE_ID=edge-1    # Identifier for this Edge instance
EDGE_TOKEN=            # Pre-shared token for Edge auth (if not using store keys)

Domains & campaigns

After logging in to the dashboard (/app/):

1. Create a campaign — a logical grouping for your traffic.
2. Add a domain to the campaign.
3. Choose the domain action: local lander (serve static HTML from Edge), redirect, or proxy.
4. For local landers, place files under content/<campaign>/site/index.html and mount the content/ folder to Edge.

Edge keys

Edge authenticates to Hub using API keys. You can manage these from the dashboard.

Create a key via API

curl -X POST http://<HUB>/api/admin/edge-tokens \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"label":"client-a","domains":["client-a.com"],"node_id":"edge-client-a"}'

Key options

• domains — restrict the key to specific domains (domain scoping)
• node_id — bind the key to a specific Edge instance (node binding)
• expires_at — optional expiry date

ClickHouse

ClickHouse is included in docker-compose.prod.yml and starts automatically. Enable it in Hub by setting:

CH_ADDR=clickhouse:9000

Apply the schema after first boot:

docker exec -i deploy-clickhouse-1 clickhouse-client < schema/clickhouse.sql

ClickHouse is optional for dev/MVP — Hub works with in-memory or Redis storage for small volumes.

TLS / HTTPS

Caddy auto-issues TLS certificates from Let's Encrypt when you use a real domain.

1. Point your domain's A record to the VPS IP.
2. Update deploy/Caddyfile.prod — replace :80 with your domain, e.g. trackifly.com.
3. Set HOST=trackifly.com in deploy/.env.
4. Restart Caddy:

docker compose -f deploy/docker-compose.prod.yml --env-file deploy/.env restart caddy

Caddy will obtain a certificate automatically on first request.

Deploy Edge on a separate VPS

Edge runs on the VPS where your domains point. One Edge node handles all domains whose DNS A record points to that VPS. To add a new domain — client just changes DNS, no reinstall or restart needed.

1. 1
   Install Docker on the domain VPS

   curl -fsSL https://get.docker.com | sh

2. 2
   Create an Edge key in Hub

   Hub dashboard → Edge Keys → New key. Copy the token value — it's shown only once.

3. 3
   Run the installer on the domain VPS

   curl -fsSL https://trackifly.com/install.sh | bash -s -- --mode edge

   The script asks for your Hub URL, the Edge token, and a node ID. That's it.

4. 4
   Add domains — just change DNS

   In Hub: create a campaign, add the domain, set its action. Then in the domain registrar: point the DNS A record to the Edge VPS IP. Edge picks up the new config automatically on next poll. Repeat for any number of domains — no reinstall, no restart.

Unattended install

curl -fsSL https://trackifly.com/install.sh | bash -s -- \
  --mode edge \
  --hub-url https://hub.example.com \
  --edge-token <token> \
  --node-id edge-client-a \
  --edge-port 8080

FAQ

Health check

Hub exposes a health endpoint at /api/healthz. Returns 200 ok when Hub is ready.

curl https://trackifly.com/api/healthz
# → ok

Use this endpoint for uptime monitoring or load balancer health checks.