Configuration & Environment Variables

Relevant source files

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

• README.md
• PROJECT_OUTLINE.md
• docker/docker-compose.yml
• prisma.config.ts
• app/web/prisma.config.ts
• package.json

Glimpse utilizes a centralized configuration system primarily driven by environment variables to manage database connections, real-time caching, geolocation services, and error tracking. The project is designed to be highly portable, supporting local standalone execution, Docker-based orchestration, and production-ready deployments.

Configuration is handled across several layers, including the root-level environment, the Docker container environment, and specific framework configurations for Prisma and Next.js.

Sources: README.md:37-45, PROJECT_OUTLINE.md:195-200

Core System Variables

The following variables are essential for the operation of the Glimpse backend and worker services. They control the primary data stores and external API integrations.

Variable	Description	Default / Example
DATABASE_URL	Connection string for the PostgreSQL database.	postgresql://postgres:postgres@localhost:5432/app
REDIS_HOST	Hostname for the Redis server.	localhost (Standalone) / redis (Docker)
REDIS_PORT	Port for the Redis server.	6379
GEOLITE_LICENSE_KEY	MaxMind license key for IP-to-location lookups.	your_maxmind_license_key_here
SENTRY_DNS	Sentry Data Source Name for error tracking.	N/A
SENTRY_ENABLED	Flag to enable or disable Sentry integration.	true (in Docker)

Sources: README.md:47-53, docker/docker-compose.yml:22-28, PROJECT_OUTLINE.md:195-199

Service Configuration Architecture

The architecture relies on these variables to link modular components. The diagram below illustrates how environment variables facilitate communication between the API, Workers, and Infrastructure.

The application services use DATABASE_URL to connect to PostgreSQL and REDIS_HOST to connect to Redis for job queuing and session caching.

Sources: docker/docker-compose.yml:1-85, PROJECT_OUTLINE.md:120-145

Database & Prisma Configuration

Prisma is configured via defineConfig in multiple locations to ensure the schema is correctly mapped regardless of the execution context (root or web application).

Root Prisma Configuration

In the root directory, prisma.config.ts points to the shared database package.

export default defineConfig({
  schema: "packages/db/prisma/schema.prisma",
  migrations: {
    path: "packages/db/prisma/migrations",
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
});

Sources: prisma.config.ts:4-13

Web-Specific Configuration

Because the web application resides in app/web/, its configuration uses relative paths to access the shared package.

export default defineConfig({
  schema: "../../packages/db/prisma/schema.prisma",
  migrations: {
    path: "../../packages/db/prisma/migrations",
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
});

Sources: app/web/prisma.config.ts:4-13

Docker Orchestration Details

When running via Docker Compose, service discovery is handled through internal networking, which overrides the local localhost defaults used in standalone installations.

Service	Environment Logic	Logic / Mapping
api	Maps port 3000 to host.	Sets REDIS_HOST: redis for internal networking.
worker	Background processing.	Shares the same DB and Redis env as the API.
postgres	Infrastructure.	Uses POSTGRES_USER and POSTGRES_DB to initialize the database.
redis	Infrastructure.	Internal port 6379 mapped to host port 6378.

Sources: docker/docker-compose.yml:7-85, README.md:68-85

Client-Side Configuration

The analytics-web SDK utilizes data attributes on the script tag for runtime configuration. This allows the tracker to identify the project and target the correct API endpoint without hardcoding values in the source.

• data-project-id: Required to scope events to a specific project.
• The tracker defaults to http://localhost:3000/event for development.

Sources: test/demo.html:121-122, PROJECT_OUTLINE.md:110-115

Summary

Glimpse relies on a unified environment configuration to bridge its TypeScript/Bun runtime with its PostgreSQL and Redis infrastructure. By using standard variables like DATABASE_URL and REDIS_HOST, the system maintains consistency across development (local Bun), testing (Docker Compose), and production environments. The dual-Prisma configuration ensures that database schema changes in the shared packages/db are accessible to both the backend services and the Next.js frontend.

Sources: README.md:150-165, PROJECT_OUTLINE.md:215-225