Skip to main content
OneGlance uses environment variables to configure services across the monorepo. This guide documents all available variables, their purpose, and configuration.

​
Configuration Files

Environment variables are stored in two locations:
  • .env (root) - Shared variables for web app, infrastructure, and Docker Compose
  • apps/agent/.env - Agent-specific variables (worker configuration, proxies)
Never commit .env files to version control. The .env.example files are provided as templates.

​
Quick Setup

Create environment files from examples: 
cp .env.example .env
cp apps/agent/.env.example apps/agent/.env

​
Database Configuration

Variables for PostgreSQL and ClickHouse database connections.
​
DATABASE_URL
string
required
PostgreSQL connection string for the main application database.Format: postgresql://[user]:[password]@[host]:[port]/[database]Example (local):
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
Example (Docker):
DATABASE_URL=postgresql://user:password@db:5432/mydb
Use localhost for local development. Use service names (db) when running in Docker Compose.
​
POSTGRES_USER
string
required
PostgreSQL username. Must match the username in DATABASE_URL.Default: user
POSTGRES_USER=user
​
POSTGRES_PASSWORD
string
required
PostgreSQL password. Must match the password in DATABASE_URL.
POSTGRES_PASSWORD=your_secure_password
Use a strong password in production. Generate with: openssl rand -base64 32
​
POSTGRES_DB
string
required
PostgreSQL database name. Must match the database in DATABASE_URL.Default: mydb
POSTGRES_DB=mydb
​
CLICKHOUSE_URL
string
required
ClickHouse HTTP interface URL for analytics data.Example (local):
CLICKHOUSE_URL=http://localhost:8123
Example (Docker):
CLICKHOUSE_URL=http://clickhouse:8123
​
CLICKHOUSE_DB
string
required
ClickHouse database name for analytics tables.Default: analytics
CLICKHOUSE_DB=analytics
​
CLICKHOUSE_USER
string
required
ClickHouse username for authentication.Default: default
CLICKHOUSE_USER=default
​
CLICKHOUSE_PASSWORD
string
required
ClickHouse password for authentication.
CLICKHOUSE_PASSWORD=your_secure_password
Use a strong password in production.

​
Application URLs

Variables for configuring application URLs and routing.
​
APP_URL
string
required
Internal server-side URL for the web application.Local development:
APP_URL=http://localhost:3000
Docker (internal):
APP_URL=http://web:3000
This URL is used for server-to-server communication within the Docker network.
​
API_BASE_URL
string
required
Base URL for internal API calls. Typically same as APP_URL.
API_BASE_URL=http://web:3000
​
BETTER_AUTH_URL
string
required
Public-facing URL for Better Auth callbacks (client-side).Development:
BETTER_AUTH_URL=http://localhost:3000
Production:
BETTER_AUTH_URL=https://app.yourdomain.com
This must be the external URL accessible from user browsers, not the internal Docker URL.
​
NEXT_PUBLIC_API_URL
string
required
Public API URL exposed to the browser (Next.js public env var).Development:
NEXT_PUBLIC_API_URL=http://localhost:3000
Production:
NEXT_PUBLIC_API_URL=https://app.yourdomain.com
Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

​
Authentication & Secrets

Variables for authentication and security.
​
BETTER_AUTH_SECRET
string
required
Secret key for signing Better Auth session tokens.
BETTER_AUTH_SECRET=your_random_secret_here
Generate a secure secret:
openssl rand -base64 32
Keep this secret secure. Changing it will invalidate all existing sessions.
​
INTERNAL_CRON_SECRET
string
required
Secret for authenticating internal cron job requests.
INTERNAL_CRON_SECRET=your_random_secret_here
Generate:
openssl rand -hex 32
​
GOOGLE_CLIENT_ID
string
Google OAuth client ID for Google authentication.
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
Obtain from Google Cloud Console.
​
GOOGLE_CLIENT_SECRET
string
Google OAuth client secret for Google authentication.
GOOGLE_CLIENT_SECRET=your-client-secret
Keep this secret secure. Never expose in client-side code.

​
Redis Configuration

Variables for Redis queue and cache.
​
REDIS_URL
string
required
Full Redis connection URL.Local development:
REDIS_URL=redis://localhost:6379
With password:
REDIS_URL=redis://:your_password@localhost:6379
Docker:
REDIS_URL=redis://redis:6379
​
REDIS_HOST
string
required
Redis server hostname.Local: localhost Docker: redis
REDIS_HOST=redis
​
REDIS_PORT
number
required
Redis server port.Default: 6379
REDIS_PORT=6379
​
REDIS_PASSWORD
string
required
Redis authentication password.
REDIS_PASSWORD=your_secure_password
This password must match in both .env and apps/agent/.env. Redis in Docker Compose uses this for authentication.

​
Agent Worker Configuration

Variables specific to the browser automation agent worker (set in apps/agent/.env).
​
AGENT_WORKER_CONCURRENCY
number
Number of concurrent browser jobs the agent can process.Default: 1
AGENT_WORKER_CONCURRENCY=1
Higher values increase throughput but require more CPU and memory. Each worker runs a separate browser instance.
​
VPS_AUTH_PROFILE_PATH
string
Path for storing browser authentication profiles and session data.Default: /storage
VPS_AUTH_PROFILE_PATH=/storage
In Docker, this maps to the agent_storage volume.

​
Proxy Configuration

Variables for configuring proxy usage in the agent worker.
​
PROXY_SOURCE_MODE
string
How the agent obtains proxy servers.Options:
  • auto - Automatically fetch from proxy API
  • manual - Read from a local file
  • none - Don’t use proxies
PROXY_SOURCE_MODE=auto
​
PROXY_API_URL
string
API endpoint to fetch proxy list (when PROXY_SOURCE_MODE=auto).
PROXY_API_URL=https://your-proxy-api.com/list
​
PROXY_MANUAL_FILE
string
Path to file containing proxy list (when PROXY_SOURCE_MODE=manual).Format: One proxy per line: host:port:username:password
PROXY_MANUAL_FILE=/storage/proxies.txt

​
External APIs

Variables for third-party service integrations.
​
OPENAI_API_KEY
string
OpenAI API key for GPT model access (used in analysis).
OPENAI_API_KEY=sk-...
Obtain from OpenAI Platform.
Keep this secret secure. Monitor usage to avoid unexpected costs.

​
Docker Configuration

​
GHCR_USERNAME
string
required
GitHub Container Registry username for pulling Docker images.
GHCR_USERNAME=your-github-username
Used in docker-compose.yml to construct image URLs:
image: ghcr.io/${GHCR_USERNAME}/oneglanse-web:latest

​
Debugging

​
DEBUG_ENABLED
boolean
Enable verbose debug logging.Default: false
DEBUG_ENABLED=false
Set to true for detailed logs during development:
DEBUG_ENABLED=true

​
Environment-Specific Configurations

​
Local Development

Minimal configuration for local development:
.env
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
POSTGRES_USER=user
POSTGRES_PASSWORD=password
POSTGRES_DB=mydb

# ClickHouse
CLICKHOUSE_URL=http://localhost:8123
CLICKHOUSE_DB=analytics
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=password

# URLs
APP_URL=http://localhost:3000
API_BASE_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:3000

# Redis
REDIS_URL=redis://localhost:6379
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=devpassword

# Secrets
BETTER_AUTH_SECRET=generate_with_openssl_rand_base64_32
INTERNAL_CRON_SECRET=generate_with_openssl_rand_hex_32

# Optional
DEBUG_ENABLED=true
AGENT_WORKER_CONCURRENCY=1
PROXY_SOURCE_MODE=none

​
Docker Compose

Configuration for Docker Compose deployment:
.env
# Use service names for internal communication
DATABASE_URL=postgresql://user:password@db:5432/mydb
CLICKHOUSE_URL=http://clickhouse:8123
REDIS_URL=redis://:password@redis:6379

# Internal URLs
APP_URL=http://web:3000
API_BASE_URL=http://web:3000

# External URLs (must be accessible from browsers)
BETTER_AUTH_URL=https://app.yourdomain.com
NEXT_PUBLIC_API_URL=https://app.yourdomain.com

# Registry
GHCR_USERNAME=your-github-username

​
Security Best Practices

Follow these security guidelines to protect your OneGlance deployment:
  1. Generate Strong Secrets 
    # For BETTER_AUTH_SECRET
openssl rand -base64 32

# For INTERNAL_CRON_SECRET
openssl rand -hex 32
  2. Use Strong Database Passwords
    • Minimum 16 characters
    • Mix of letters, numbers, and symbols
    • Different passwords for each service
  3. Never Commit Secrets
    • Ensure .env is in .gitignore
    • Use .env.example with placeholder values
    • Rotate secrets regularly
  4. Restrict Access
    • Use environment-specific values
    • Limit database user permissions
    • Use read-only credentials where possible
  5. Monitor API Keys
    • Track OpenAI API usage
    • Set up billing alerts
    • Rotate keys periodically
  6. Secure Redis
    • Always set REDIS_PASSWORD in production
    • Don’t expose Redis port publicly
    • Use TLS for Redis in production

​
Validation

Verify your environment configuration:
1

Check required variables

Ensure all required variables are set and not using placeholder values like changeme.
2

Test database connections

# PostgreSQL
docker compose exec db psql -U $POSTGRES_USER -d $POSTGRES_DB -c "SELECT 1"

# ClickHouse
docker compose exec clickhouse clickhouse-client --user $CLICKHOUSE_USER --password $CLICKHOUSE_PASSWORD --query "SELECT 1"

# Redis
docker compose exec redis redis-cli -a $REDIS_PASSWORD ping
3

Verify app startup

Check application logs for connection errors:
pnpm dev:web
# Look for successful database and Redis connections

​
Troubleshooting

Problem: Application can’t connect to services.Solution:
  • For local dev, use localhost in URLs
  • For Docker, use service names (db, redis, clickhouse)
  • Ensure services are running: docker compose ps
Problem: Database authentication errors.Solution:
  • Verify credentials match in DATABASE_URL and POSTGRES_* variables
  • Check passwords don’t contain special characters that need URL encoding
  • Recreate services: docker compose down -v && docker compose up -d
Problem: Changes to .env not taking effect.Solution:
  • Restart the application after changing .env
  • For Docker: docker compose down && docker compose up -d
  • Clear Next.js cache: rm -rf apps/web/.next

​
Next Steps

Local Setup

Complete local development setup guide

Docker Compose

Learn about the Docker Compose architecture