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.