Docker Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• docker/docker-compose.yml
• README.md
• PROJECT_STRUCTURE.md
• PROJECT_OUTLINE.md
• package.json
• app/workers/eventWorker.ts

Docker Deployment in the Glimpse project provides a containerized environment for local development and production-ready service orchestration. It encapsulates the core API, background workers, and persistent data stores (PostgreSQL and Redis) to ensure consistent behavior across different environments. This approach automates the setup of the complex multi-service architecture required for real-time analytics.

The deployment relies on Docker Compose to manage five primary services that communicate over an internal network. It handles environment variable injection, volume persistence for databases, and port mapping for external access to the API and data layers.

Sources: README.md:85-88, docker/docker-compose.yml:1-77

Service Architecture

The Glimpse architecture is divided into application services and infrastructure services. All application services are built using a unified Dockerfile and leverage the Bun runtime for high-performance execution of TypeScript code.

Infrastructure Components

• Postgres: A PostgreSQL 16 database used for long-term storage of events, sessions, and aggregates.
• Redis: A Redis 7 instance serving as the message broker for BullMQ and a real-time session cache with a 300-second TTL.

Application Components

• API: The entry point for event ingestion and frontend communication, exposed on port 3000.
• Worker: The primary event processing service that handles geolocation lookups and initial session storage.
• Analytics-Worker: A specialized worker focused on downstream analytics processing.

Configuration and Environment

The deployment is configured via environment variables, primarily managed through a .env file located in the docker/ directory. These variables control database connections, caching behavior, and external integrations like MaxMind GeoIP.

Environment Variables

Variable	Description	Default Value
GEOLITE_LICENSE_KEY	License key for MaxMind IP geolocation	(Required)
DATABASE_URL	Connection string for PostgreSQL	postgresql://postgres:postgres@postgres:5432/app
REDIS_HOST	Hostname for the Redis service	redis
REDIS_PORT	Port for the Redis service	6379
SENTRY_DNS	DSN for Sentry error tracking	(Optional)

Sources: docker/docker-compose.yml:17-25, README.md:65-74, README.md:104-109

Data Persistence and Networking

To ensure data survives container restarts, Docker Compose uses named volumes and host-mounted volumes.

• Postgres Data: Persisted via a named volume pg_data mapped to /var/lib/postgresql/data.
• Source Code: The root repository is mounted to /repo within the containers to support hot-reloading during development via bun --watch.
• Port Mapping:
  • API: 3000:3000
  • Postgres: 5432:5432
  • Redis: 6378:6379 (Mapped to 6378 on host to avoid local conflicts)

Sources: docker/docker-compose.yml:13-14, docker/docker-compose.yml:68-70, docker/docker-compose.yml:72-77

Deployment Workflow

The standard deployment follows a structured sequence of commands to build, initialize, and migrate the system.

Initialization Sequence

Deployment Commands

# 1. Build and start services in the background
docker-compose up -d --build

# 2. Apply database migrations inside the running API container
docker-compose exec api bun run prisma:migrate

Sources: README.md:112-118, README.md:204-207

Technical Implementation Details

The containers use specific commands to execute the different parts of the monorepo:

• API: bun --watch --poll run index.ts
• Worker: bun --watch --poll run workers.ts
• Analytics Worker: bun --watch --poll run app/analytics-worker/analyticsWorker.ts

The PRISMA_CLIENT_ENGINE_TYPE is set to library within the environment to optimize database interactions within the Linux containers.

Sources: docker/docker-compose.yml:11, docker/docker-compose.yml:34, docker/docker-compose.yml:52, package.json:16-18

Summary

The Docker Deployment for Glimpse provides a robust, reproducible environment for managing the platform's multi-service architecture. By orchestrating the Bun-based application logic alongside high-performance data stores like Redis and PostgreSQL, it enables seamless scaling and efficient local development through volume-mounted source code and automated background job processing.