Installation

Detailed installation instructions for all Email Tracker components

This guide covers the complete installation process for Email Tracker, including all components and configurations.

System requirements

• Node.js v18 or higher
• npm, yarn, or pnpm
• Chrome browser (for the extension)
• Git

Installation steps

Clone the repository

First, clone the Email Tracker repository:

git clone <your-fork-or-repo-url>
cd email-tracker

Install dependencies

Install all dependencies for the monorepo:

npm

npm install

yarn install

pnpm install

This installs dependencies for all workspaces:

• extension/ - Chrome extension (MV3)
• server/ - Express tracker + dashboard + SQLite
• shared/ - Shared token/types package

Build the workspaces

Build the shared library and server packages in order:

1. Build the shared package

   The shared package contains token encoding/decoding logic used by both the server and extension:

   npm

   npm --workspace=shared run build
   

   yarn workspace shared build
   

   pnpm --filter shared build
   
2. Build the server package

   Build the TypeScript server to JavaScript:

   npm

   npm --workspace=server run build
   

   yarn workspace server build
   

   pnpm --filter server build
   

   The extension does not require a build step as it uses vanilla JavaScript.

Start the server

Start the tracking server with required environment variables:

npm

PORT=8090 DASHBOARD_TOKEN=change-me npm --workspace=server run start

PORT=8090 DASHBOARD_TOKEN=change-me yarn workspace server start

PORT=8090 DASHBOARD_TOKEN=change-me pnpm --filter server start

Replace change-me with a strong, random token. Keep this token private as it protects access to your tracking dashboard.

Verify server health

Check that the server is running correctly:

curl http://localhost:8090/health

You should receive a successful response indicating the server is ready.

Load the Chrome extension

Install the extension in Chrome using Developer mode:

1. Open Chrome extensions

   Navigate to chrome://extensions in your Chrome browser.

2. Enable Developer mode

   Toggle Developer mode on using the switch in the top right corner.

3. Load unpacked extension

   1. Click the Load unpacked button
   2. Navigate to your Email Tracker installation directory
   3. Select the extension/ folder
   4. Click Select or Open
4. Verify installation

   The Gmail Email Tracker extension should now appear in your extensions list and toolbar.

Configure extension settings

Set up the extension to communicate with your tracking server:

1. Open extension popup

   Click the Email Tracker extension icon in your Chrome toolbar.

2. Set Tracker Base URL

   Enter your tracker URL:

   • For local development: http://localhost:8090
   • For production: your HTTPS domain (e.g., https://tracker.yourdomain.com)

   Production deployments must use HTTPS. Many email clients block or downgrade non-HTTPS assets.

3. Set Dashboard Token

   Enter the same DASHBOARD_TOKEN value you used when starting the server.

4. Save settings

   Save your configuration. The extension is now ready to track emails.

Production deployment

For production use, you’ll need additional setup:

HTTPS requirement

You must use HTTPS in production. Many email clients block or downgrade non-HTTPS assets, which will prevent tracking pixels from loading.

Required infrastructure

1. Domain: Point your domain DNS to your server
2. Firewall: Open ports 80 and 443
3. Node server: Run on localhost (e.g., 127.0.0.1:8090)
4. Reverse proxy: Use Caddy or Nginx to:
   • Terminate TLS
   • Proxy requests to your Node server

Sample reverse proxy configurations are available in the deploy/ directory:

• deploy/Caddyfile
• deploy/nginx-email-tracker.conf

Process management

Run the server with a process manager for reliability:

• systemd: For Linux system services
• pm2: Cross-platform process manager

Example with pm2:

pm2 start "npm --workspace=server run start" --name email-tracker

Repository structure

Understanding the project layout:

email-tracker/
├── extension/          # Chrome extension (MV3)
│   ├── src/
│   │   ├── background/ # Service worker, token generation
│   │   ├── content/    # Gmail integration, pixel injection
│   │   └── popup/      # Extension settings UI
│   └── manifest.json
├── server/             # Express API + dashboard
│   ├── src/
│   │   ├── routes/     # Pixel tracking, dashboard APIs
│   │   ├── services/   # Recording logic, GeoIP
│   │   └── db/         # SQLite schema and initialization
│   └── package.json
├── shared/             # Shared token/types package
└── deploy/             # Sample reverse proxy configs

Next steps

• Configure environment variables for your deployment
• Review the quickstart guide for testing
• Set up monitoring and backups for production use