Installation

Learn how to install the Psyduck Tracker on your website. This guide covers both the client-side tracking code and server-side setup.

Prerequisites

Before installing the Psyduck Tracker, you need:

A running Psyduck Analytics server
Access to your website's HTML code
Basic knowledge of HTML and JavaScript

Server Setup

First, you'll need to have the Psyduck Analytics server running. If you haven't set it up yet:

# Clone the repository
git clone https://github.com/your-repo/psyduck.git

# Install dependencies
cd psyduck
pnpm install

# Start the server
pnpm dev

The server will be available at http://localhost:9876.

Database Migration

The Psyduck Tracker uses DuckDB as its database. Before starting the server, you need to run the database migrations to set up the required tables and types.

Running Migrations

To apply all pending migrations:

pnpm migrate

This will:

Create the device_type enum (mobile, tablet, desktop)
Create the events table with all required columns
Track which migrations have been applied

Migration Options

You can customize the migration process:

# Use a custom database file
pnpm migrate --db ./custom.db

# Use a custom migrations directory
pnpm migrate --migrations ./custom-migrations

# Rollback the last migration
pnpm migrate down

# Rollback a specific number of migrations
pnpm migrate down --number 2

# Rollback all migrations
pnpm migrate down --number all

Migrations are run automatically when starting the development server via pnpm dev.

Configuration Initialization

The Psyduck Tracker requires initial configuration including a JWT key and at least one user account.

Automatic Configuration

When you run pnpm dev, the system automatically runs the configuration initialization script (bin/config.ts) which:

Checks if a JWT key exists and generates one if needed
Checks if any users exist and prompts for the creation of an initial user if none exist

Manual Configuration

If you need to manually initialize the configuration:

# This runs automatically with pnpm dev, but can be run separately
pnpm prepare-config

Adding Additional Users

To add additional users after the initial setup:

pnpm prepare-config -- --add-user

This will prompt you to enter an email and password for the new user.

Configuration File

The configuration is stored in data/config.json with the following structure:

{
  "users": [
    {
      "email": "user@example.com",
      "password": "hashed_password"
    }
  ],
  "jwtKey": "your-jwt-secret-key",
  "demoMode": false
}

When demoMode is set to true, analytics endpoints are accessible without authentication, which is useful for development and testing.

Client-Side Installation

There are two ways to install the tracker on your website:

Option 1: Script Tag (Recommended)

Add the following script tag to the <head> section of your HTML pages:

<script 
  src="https://tracker.psyduck.click/track.js" 
  data-domain="https://tracker.psyduck.click" 
  defer>
</script>

Alternatively, you can use your self-hosted instance:

<script 
  src="http://localhost:9876/track.js" 
  data-domain="http://localhost:9876" 
  defer>
</script>

The hosted version at https://tracker.psyduck.click is recommended for most users as it requires no server setup.

Option 2: Manual Initialization

If you need more control over when the tracker initializes, you can load the script manually and initialize it:

<script src="https://tracker.psyduck.click/track.js" defer></script>
<script>
  // Initialize the tracker after the script loads
  window.addEventListener('load', function() {
    Psyduck.init({
      domain: 'https://tracker.psyduck.click'  // Recommended hosted domain
      // or
      // domain: 'https://your-psyduck-server.com'  // Self-hosted instance
    });
  });
</script>

Verification

To verify that tracking is working:

Open your website in a browser
Open the browser's developer tools (F12)
Go to the Network tab
Refresh the page
Look for requests to your Psyduck server

You should see a POST request to /events with event data.

Running the Server

After installation and configuration, you can run the Psyduck Tracker server in different ways:

Development Mode

For development with hot reloading:

# Run the development server (includes auto-migration and config setup)
pnpm dev

This command automatically:

Runs database migrations if needed
Sets up initial configuration (JWT key and user)
Starts the server with hot reloading
Makes the server available at http://localhost:9876

Production Mode

For production deployment, you would run:

# Just the server without development features
pnpm run dev:standalone

Running Multiple Services

If you want to run the tracking library development server alongside the main server:

# Run the main server in one terminal
pnpm dev

# Run the tracking library server in another terminal
pnpm --filter=@psyduck/track dev

All-in-One Development

To run all services simultaneously:

pnpm run dev:all

This starts both the main server and the tracking library development server.

Next Steps

Once installed, check out the Configuration Guide to learn how to customize your tracking settings.

Installation

On this page