Skip to main content
Email Tracker is designed to be self-hosted, giving you full control over your tracking data and infrastructure.

​
What you need to configure

When self-hosting Email Tracker, you need to set up:
  1. Your own domain (recommended) or host/IP
  2. HTTPS reverse proxy for production email clients
  3. Server port (PORT environment variable)
  4. Strong dashboard token (DASHBOARD_TOKEN environment variable)
  5. Extension configuration (tracker URL + dashboard token in popup)
This is the minimum configuration for a working deployment.

​
Server environment variables

​
Required variables

​
DASHBOARD_TOKEN
string
required
Secret token for authenticating dashboard API requests. Keep this private and use a strong random value.

​
Optional variables

​
PORT
number
default:"8080"
Port for the Node.js server to listen on. Use 127.0.0.1:PORT when running behind a reverse proxy.
​
DB_PATH
string
default:"server/data/tracker.db"
Path to the SQLite database file.
​
DEDUP_WINDOW_MS
number
default:"30000"
Deduplication window in milliseconds. Opens within this window from the same source are treated as duplicates.

​
Extension configuration

After loading the Chrome extension, configure it through the popup:
  1. Tracker Base URL
    • For local development: http://localhost:8090
    • For production: Your HTTPS domain (e.g., https://tracker.yourdomain.com)
  2. Dashboard Token
    • Must match the DASHBOARD_TOKEN environment variable on your server

​
Operational recommendations

​
Process management

Run the server with a process manager to ensure it stays running:
Create a systemd service file at /etc/systemd/system/email-tracker.service:
[Unit]
Description=Email Tracker Server
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/email-tracker
Environment="PORT=8090"
Environment="DASHBOARD_TOKEN=your-secure-token"
ExecStart=/usr/bin/npm --workspace=server run start
Restart=always

[Install]
WantedBy=multi-user.target
Enable and start the service:
sudo systemctl enable email-tracker
sudo systemctl start email-tracker

​
Database backups

Regularly back up your SQLite database file to prevent data loss: 
# Create a backup with timestamp
cp server/data/tracker.db server/data/tracker.db.$(date +%Y%m%d_%H%M%S)

# Or use SQLite's backup command for a consistent snapshot
sqlite3 server/data/tracker.db ".backup 'tracker-backup.db'"
Consider setting up automated backups with a cron job: 
# Run daily at 2 AM
0 2 * * * cd /path/to/email-tracker && sqlite3 server/data/tracker.db ".backup 'backups/tracker-$(date +\%Y\%m\%d).db'"

​
Log rotation

Monitor disk usage and rotate logs regularly:
  • If using systemd, logs are automatically managed by journald
  • If using pm2, configure log rotation:
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7

​
Security best practices

Keep your DASHBOARD_TOKEN private. Anyone with this token can access your tracking dashboard and analytics data.
  • Use a strong, randomly generated DASHBOARD_TOKEN
  • Never commit the token to version control
  • Use environment variables or a secrets management system
  • Regularly rotate the token and update your extension configuration

​
Storage considerations

The SQLite database stores:
  • tracked_emails: Email metadata and open counts
  • open_events: Individual open events with IP, User-Agent, and GeoIP data
Disk usage grows with the number of tracked emails and opens. Monitor the database size and consider implementing data retention policies if needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us