Trackily Docs

Installation

Deux chemins : binaire Node natif (le plus rapide à essayer) ou docker compose (le plus propre pour la prod). Les deux marchent identiquement — choisis selon ton serveur.

Dashboard Trackily après installation

À quoi ça sert

Trackily est livré en deux saveurs :

  • Binaire pkg — un seul fichier trackily qui contient Node.js + le code + les assets. Tu copies, tu lances, c'est plié. Idéal pour un VPS simple ou pour tester en local.
  • Docker Compose — trackily + postgres + (optionnellement) Caddy pour le SSL auto. C'est le mode recommandé pour la prod parce que la base est isolée, les certs persistent, et un docker compose up -d suffit pour repartir après reboot.

Dans les deux cas, la base PostgreSQL est gérée par toi (Trackily ne ship pas Postgres en dur dans le binaire). Trackily ouvre la connexion via DATABASE_URL, applique toutes les migrations au boot (table par table, idempotent) et crée le user admin si la table users est vide.

Pré-requis

Composant Version mini Notes
Node.js 22.14.0 Requis seulement pour le mode binaire / dev. Le mode Docker ship Node dans l'image.
PostgreSQL 14 16-alpine recommandé. Neon, Supabase et Render fonctionnent (SSL est auto-détecté via l'URL).
RAM 1 GB 2 GB recommandés si tu utilises l'AI landing builder.
Ports 3000 + 80/443 si tu actives AUTO_SSL=true (Caddy reverse proxy).

Variables d'environnement

Trackily lit son .env au boot via dotenv. Voici les variables qui comptent vraiment :

# ─── Obligatoires ───────────────────────────
DATABASE_URL=postgres://trackily:secret@localhost:5432/trackily
ADMIN_PASSWORD=ChangeMoiUnMotDePasseLong          # ≥ 8 caractères, sinon refus de démarrer

# ─── Recommandées ───────────────────────────
PORT=3000                                          # défaut 3000
BASE_URL=https://tracker.exemple.com               # URL publique (utilisée pour les postbacks, magic links, etc.)
SECRETS_KEY=                                       # 32 bytes hex pour chiffrer les API keys stockées en DB
LICENSE_KEY=                                       # facultatif — vide = mode dev illimité

# ─── Docker / Caddy ─────────────────────────
AUTO_SSL=true                                      # active Caddy + Let's Encrypt sur les ports 80/443
DB_PASSWORD=trackily_secure_2024                   # mot de passe Postgres (utilisé par docker-compose)

ADMIN_PASSWORD est vérifié au boot : moins de 8 caractères ou variable manquante = [FATAL] et le process s'arrête. C'est volontaire pour éviter de booter avec un défaut faible. Voir server.js:626.

DATABASE_URL est nettoyé automatiquement (les paramètres sslmode et channel_binding sont retirés et reconstruits selon l'hôte). Voir database.js:4.

Si l'URL contient neon.tech, supabase, render.com ou sslmode=require, le SSL est activé en mode rejectUnauthorized: false. Pour un Postgres self-hosted dans le même réseau, laisse DATABASE_URL sans sslmode — la connexion sera en clair (LAN privé).

Option A — Binaire natif

C'est le chemin le plus court pour tester.

# 1. Cloner / récupérer le repo
git clone https://github.com/ton-org/trackily.git
cd trackily

# 2. Installer les deps
npm install

# 3. Configurer .env
cat > .env <<EOF
DATABASE_URL=postgres://trackily:secret@localhost:5432/trackily
ADMIN_PASSWORD=MonMotDePasseLongEtFort
PORT=3000
BASE_URL=http://localhost:3000
EOF

# 4. Préparer la base (Postgres doit déjà tourner)
createdb -U postgres trackily

# 5. Lancer
npm start

Au premier boot tu verras dans les logs :

[DB] Applying migrations…
[DB] Migration v1 applied
[DB] Migration v2 applied
… (jusqu'à la dernière version)
[DB] Seeded built-in cloaking workflow: "VPN Blocker (Built-in)"
[Auth] Admin user seeded: admin@trackily.local
[Automizer] Starting rule engine (60s interval)
[License] No LICENSE_KEY set — running in development mode (all features)
[Trackily] Listening on http://localhost:3000

Ouvre http://localhost:3000/admin → voir Première connexion.

Mode dev (auto-reload)

npm run dev

Lance le serveur avec node --watch — chaque modif d'un .js redémarre Trackily. Utile pour développer un MCP tool ou tweaker un template.

Build d'un binaire standalone

npm run build:linux      # binaire Linux x64
npm run build:mac        # binaire macOS x64
npm run build:all        # les deux

Sort un fichier dist/trackily (~50 MB compressé GZip) qui n'a besoin que de DATABASE_URL et ADMIN_PASSWORD dans l'env pour tourner. Pas de node_modules à shipper.

Option B — Docker Compose

Recommandé pour la prod. Fichier livré dans dist/docker-compose.yml :

version: "3.8"
services:
  trackily:
    build: .
    restart: always
    ports:
      - "${PORT:-3000}:3000"
      - "80:80"     # Requis pour AUTO_SSL=true
      - "443:443"   # Requis pour AUTO_SSL=true
    env_file: .env
    depends_on:
      - postgres
    volumes:
      - trackily-data:/app/data
      - caddy-data:/data        # Certs Caddy (persistants)
  postgres:
    image: postgres:16-alpine
    restart: always
    environment:
      POSTGRES_DB: trackily
      POSTGRES_USER: trackily
      POSTGRES_PASSWORD: ${DB_PASSWORD:-trackily_secure_2024}
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:
  trackily-data:
  caddy-data:

Lancer

cd dist/
cat > .env <<EOF
DATABASE_URL=postgres://trackily:trackily_secure_2024@postgres:5432/trackily
ADMIN_PASSWORD=MonMotDePasseLongEtFort
DB_PASSWORD=trackily_secure_2024
BASE_URL=https://tracker.exemple.com
AUTO_SSL=true
EOF

docker compose up -d
docker compose logs -f trackily

Le Dockerfile (récap)

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y \
    ca-certificates curl debian-keyring debian-archive-keyring \
    apt-transport-https gnupg && \
    # install Caddy depuis le repo officiel
    curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg && \
    curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list && \
    apt-get update && apt-get install -y caddy
WORKDIR /app
COPY trackily /app/trackily
COPY public /app/public
COPY Caddyfile /app/Caddyfile
COPY start.sh /app/start.sh
RUN chmod +x /app/trackily /app/start.sh
EXPOSE 3000 80 443
CMD ["/app/start.sh"]

L'image embarque Caddy pour faire reverse proxy + SSL automatique Let's Encrypt. Si AUTO_SSL=false (ou non défini), Caddy n'est pas lancé et Trackily écoute directement sur ${PORT}.

Le start.sh

#!/bin/bash
set -e

if [ "${AUTO_SSL}" = "true" ]; then
  echo "[Trackily] Auto-SSL activé — Caddy sur ports 80/443"
  caddy start --config /app/Caddyfile --adapter caddyfile
else
  echo "[Trackily] Auto-SSL désactivé — Trackily direct sur ${PORT:-3000}"
fi

exec /app/trackily

Le premier boot en détail

Trackily fait beaucoup au démarrage. Dans l'ordre :

  1. Charge .env via dotenv.
  2. Vérifie ADMIN_PASSWORD — fatal si < 8 caractères.
  3. Connecte Postgres via pg.Pool. Si la base n'existe pas, ça plante avec un message explicite.
  4. Applique les migrations une par une. Chaque migration vérifie sa propre version dans la table schema_migrations et skip si déjà appliquée. Tu peux relancer Trackily 100 fois — rien ne sera dupliqué.
  5. Seed les données built-in :
    • Le workflow de cloaking "VPN Blocker (Built-in)" (voir database.js:3931).
    • Le user admin admin@trackily.local avec le mot de passe de ADMIN_PASSWORD (voir database.js:3248).
    • Les conversion types Keitaro-style (lead, sale, rebill, etc.).
  6. Démarre l'Automizer (boucle 60s, voir automizer.js:16).
  7. Vérifie la licence via license-client.js si LICENSE_KEY est défini. Sans clé = mode dev illimité.
  8. Enregistre les outils Autopilot/MCP (~150 tools — voir MCP).
  9. Écoute sur PORT.

Postgres : trois setups recommandés

Postgres local (binaire ou Docker single-container)

DATABASE_URL=postgres://trackily:secret@localhost:5432/trackily

Le plus simple. Sauvegardes via pg_dump cron.

Postgres managé (Neon / Supabase / Render)

DATABASE_URL=postgres://user:pass@ep-cool-name.neon.tech/trackily?sslmode=require

Trackily détecte le hostname et active automatiquement SSL. Aucune autre conf à faire.

Postgres dans le même Docker network (mode docker compose)

DATABASE_URL=postgres://trackily:trackily_secure_2024@postgres:5432/trackily

Le hostname postgres est résolu par le DNS interne de Docker. Pas de SSL nécessaire (LAN privé).

Erreurs courantes

  • [FATAL] ADMIN_PASSWORD env var is required and must be at least 8 characters — t'as oublié ADMIN_PASSWORD dans .env, ou il fait moins de 8 caractères. Refus volontaire de booter.
  • error: password authentication failed for user "trackily" — le user Postgres existe mais le mot de passe ne matche pas. Vérifie DATABASE_URL vs le POSTGRES_PASSWORD du container.
  • ECONNREFUSED 127.0.0.1:5432 — Postgres n'est pas démarré ou n'écoute pas sur l'adresse. pg_isready -h localhost pour vérifier.
  • Port 80/443 déjà pris quand AUTO_SSL=true — un Nginx ou Apache local mange déjà les ports. Soit tu arrêtes l'autre service, soit tu désactives Caddy et tu mets Trackily derrière ton reverse proxy existant.
  • Tables vides après reboot — si tu utilises Docker sans volume nommé pour Postgres, les données disparaissent. Le docker-compose.yml fourni utilise un volume pgdata exprès pour éviter ça.

Voir aussi