Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
Glimpse is a real-time user analytics platform designed to track sessions and visualize traffic patterns through live mapping and event streams. This guide provides the necessary steps to set up the environment, deploy the core services using Docker or standalone configurations, and integrate the tracking SDK.
Sources: README.md:1-15, PROJECT_OUTLINE.md:3-8
System Prerequisites and Environment
Before deploying Glimpse, ensure the following software versions are installed on the host system:
| Requirement | Version | Purpose |
|---|---|---|
| Bun | v1.3.6+ | Runtime for API and Workers |
| PostgreSQL | 16+ | Primary data storage |
| Redis | 7+ | Job queuing (BullMQ) and session caching |
| Docker & Compose | Latest | Containerized orchestration |
| MaxMind License | GeoLite2 | IP-based geolocation lookups |
Sources: README.md:33-38, PROJECT_OUTLINE.md:14-25
Configuration
Create a .env file in the root directory with the following parameters:
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/app"
REDIS_HOST="localhost"
REDIS_PORT="6379"
GEOLITE_LICENSE_KEY="your_maxmind_license_key_here"
Sources: README.md:42-50
Installation Options
Option 1: Docker Deployment (Recommended for Dev)
Docker Compose orchestrates the API, Worker, Database, and Redis services simultaneously.
- Clone and Enter Directory:
git clone https://github.com/Izume01/Glimpse.git cd Glimpse/docker - Launch Services:
docker-compose up --build - Initialize Database:
docker-compose exec api bun run prisma:migrate
Sources: README.md:57-88, docker/docker-compose.yml:1-71
Option 2: Standalone Installation
For granular control, services can be run individually using the Bun runtime.
# Install dependencies
bun install
# Update GeoIP Database (Required)
cd node_modules/geoip-lite && npm run updatedb license_key=YOUR_LICENSE_KEY
# Setup Database
bun run prisma:generate
bun run prisma:migrate
# Start Services
bun run dev # API Service (Port 3000)
bun run worker # Background Event Processing
Sources: README.md:95-139, package.json:11-19
Application Architecture
The Glimpse architecture utilizes a decoupled producer-consumer model via Redis-backed queues.
The diagram shows the data flow from client ingestion to background processing and storage.
Sources: PROJECT_OUTLINE.md:121-149, PROJECT_STRUCTURE.md:73-85
Web Application Setup
The frontend is a Next.js application located in app/web. It requires a separate process if not using the unified Docker build.
cd app/web
bun install
PORT=3001 bun run dev
The web interface is accessible at http://localhost:3001.
Sources: README.md:144-156, app/web/README.md:7-16
Verifying the Setup
SDK Integration
To track events on a website, include the Glimpse script with a valid data-project-id.
<script
type="module"
src="https://cdn.jsdelivr.net/npm/analytics-web-glimpse-tracker/dist/index.js"
data-project-id="your_project_id">
</script>
Sources: test/demo.html:125-126
Manual Event Testing
You can verify the API ingestion using the provided shell script or curl:
# Using the test script
./test/fire_event.sh
# Using curl directly
curl -X POST http://localhost:3000/event \
-H "Content-Type: application/json" \
-d '{"projectId": "test", "event": "ping", "sessionId": "s1"}'
Sources: test/fire_event.sh:1-12, PROJECT_OUTLINE.md:204-208
Summary
By following this guide, you deploy a full-stack analytics pipeline including a Hono-based API for event ingestion, a BullMQ worker for asynchronous geolocation processing, and a Next.js dashboard for real-time visualization. Ensure the GeoIP database is updated to enable the live mapping features.
Sources: README.md:162-178, PROJECT_OUTLINE.md:182-192