Manual Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Manual deployment of Glimpse involves configuring and running three distinct services: the API Service, the Worker Service, and the Frontend Web Application. This process allows for standalone execution of components outside of the automated Docker orchestration, which is useful for production environments or specialized development setups.
The system relies on a Bun-based TypeScript runtime and requires external dependencies including PostgreSQL 16+, Redis 7+, and a valid MaxMind GeoLite2 license for IP geolocation.
Sources: README.md:57-59, PROJECT_OUTLINE.md:10-25
Infrastructure Requirements
Before deploying Glimpse manually, the environment must be provisioned with specific technologies and configuration variables.
Prerequisites
| Requirement | Minimum Version | Purpose |
|---|---|---|
| Bun | v1.3.6+ | Backend and Worker runtime |
| PostgreSQL | 16+ | Persistent storage for events and sessions |
| Redis | 7+ | Job queue (BullMQ) and session caching |
| MaxMind Key | Free/Paid | IP-based geolocation lookups |
Sources: README.md:34-40, PROJECT_OUTLINE.md:11-20
Environment Configuration
A .env file must be created in the root directory to define service connectivity.
# Database Configuration
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/app"
# Redis Configuration
REDIS_HOST="localhost"
REDIS_PORT="6379"
# MaxMind GeoLite2 License Key
GEOLITE_LICENSE_KEY="your_maxmind_license_key_here"
Sources: README.md:44-55
Service Deployment Workflow
The deployment follows a linear progression: environment setup, database initialization, and service execution.
The diagram above illustrates the sequential steps required to manually bring the Glimpse platform online.
Sources: README.md:100-160
1. Dependency Installation
The project uses Bun for package management. Initial setup requires installing root dependencies and manually updating the geoip-lite database with the MaxMind license key.
bun install
cd node_modules/geoip-lite && npm run updatedb license_key=YOUR_LICENSE_KEY
Sources: README.md:100-112
2. Database Schema Deployment
Glimpse uses Prisma ORM to manage the PostgreSQL schema. The schema is centrally located in packages/db/prisma/schema.prisma.
bun run prisma:generate
bun run prisma:migrate
Sources: README.md:118-124, package.json:44
3. Service Execution
Each service must be started, typically in separate terminal sessions or process managers.
API Service
Handles HTTP and WebSocket traffic on port 3000.
- Command:
bun run dev(orbun index.ts) - Source File:
index.ts
Worker Service
Processes the ingest-event queue from Redis and performs Geolocation lookups.
- Command:
bun run worker - Source File:
workers.ts
Web Application (Frontend)
A Next.js application located in app/web/. It should be run on a different port (e.g., 3001) to avoid conflicts with the API.
- Command:
cd app/web && bun run dev
Sources: README.md:130-170, PROJECT_STRUCTURE.md:10-30
Component Architecture
Manual deployment requires an understanding of how these distributed components communicate via Redis and the Database.
The sequence diagram demonstrates the data flow during manual operation, highlighting the asynchronous nature of event ingestion.
Sources: PROJECT_OUTLINE.md:130-170, PROJECT_STRUCTURE.md:70-85
Service Discovery and Ports
When deploying manually, port management is critical as multiple services run on the same host.
| Service | Default Port | File/Entry Point | Description |
|---|---|---|---|
| API | 3000 | index.ts | Hono-based event ingestion |
| Web | 3001 | app/web/ | Next.js Dashboard |
| PostgreSQL | 5432 | N/A | Persistent event store |
| Redis | 6379 | N/A | BullMQ and session cache |
Sources: README.md:162-172, docker/docker-compose.yml:11-66
Summary
Manual deployment provides granular control over the Glimpse lifecycle. By separating the API, Worker, and Frontend services, administrators can scale individual components based on traffic. Success depends on the correct sequence of updating the GeoIP database, running Prisma migrations, and ensuring Redis is accessible to both the API and Worker processes.