Skip to content

configuration.md

Latest commit

 

History

History
220 lines (169 loc) · 6.46 KB

configuration.md

File metadata and controls

220 lines (169 loc) · 6.46 KB

Configuration Guide

This guide covers all configuration options for Monoscope.

Configuration Methods

Monoscope can be configured through:

  1. Environment variables (recommended)
  2. .env file
  3. Docker Compose environment section

Core Configuration

Server Settings

Variable Description Default Required
PORT HTTP server port 8080 No
GRPC_PORT gRPC server port for OpenTelemetry 4317 No
ENVIRONMENT Environment (DEV/STAGING/PROD) DEV No
HOST_URL Public URL of your Monoscope instance http://localhost:8080 No

Database Configuration

Variable Description Default Required
DATABASE_URL PostgreSQL connection string - Yes
MIGRATE_AND_INITIALIZE_ON_START Run migrations on startup True No
MIGRATIONS_DIR Path to migration files /app/static/migrations/ No

Example DATABASE_URL:

postgresql://user:password@localhost:5432/monoscope?sslmode=disable

Authentication

Basic Authentication

Variable Description Default
BASIC_AUTH_ENABLED Enable basic auth True
BASIC_AUTH_USERNAME Username admin
BASIC_AUTH_PASSWORD Password changeme

Auth0 Configuration

Variable Description Required
AUTH0_DOMAIN Auth0 domain Yes (if using Auth0)
AUTH0_CLIENT_ID Auth0 client ID Yes (if using Auth0)
AUTH0_SECRET Auth0 client secret Yes (if using Auth0)
AUTH0_CALLBACK Callback URL Yes (if using Auth0)
AUTH0_LOGOUT_REDIRECT Logout redirect URL Yes (if using Auth0)

Storage & Data Processing

Variable Description Default
API_KEY_ENCRYPTION_SECRET_KEY Secret for API key encryption (min 32 chars) -
MESSAGES_PER_PUBSUB_PULL_BATCH Batch size for message processing 100
ENABLE_BACKGROUND_JOBS Enable background job processing True
MAX_CONCURRENT_JOBS Maximum concurrent background jobs 4
ENABLE_DAILY_JOB_SCHEDULING Enable daily scheduled jobs True

OpenTelemetry & Ingestion

Variable Description Default
TELEMETRY_PROJECT_ID Project ID for telemetry data -
TELEMETRY_SERVICE_NAME Service name for telemetry monoscope
ENABLE_EVENTS_TABLE_UPDATES Enable events table updates True

Notification Services

Email Configuration (SendGrid)

Variable Description
SENDGRIDAPIKEY SendGrid API key

Email Configuration (SMTP)

Variable Description
SMTP_HOST SMTP server hostname
SMTP_PORT SMTP server port
SMTP_USERNAME SMTP username
SMTP_PASSWORD SMTP password
SMTP_SENDER From email address

Slack Integration

Variable Description
SLACK_CLIENT_ID Slack app client ID
SLACK_CLIENT_SECRET Slack app client secret
SLACK_REDIRECT_URI Slack OAuth redirect URI
SLACK_BOT_TOKEN Slack bot token

Discord Integration

Variable Description
DISCORD_CLIENT_ID Discord app client ID
DISCORD_CLIENT_SECRET Discord app client secret
DISCORD_REDIRECT_URI Discord OAuth redirect URI
DISCORD_BOT_TOKEN Discord bot token
DISCORD_WEBHOOK_URL Discord webhook URL

AI & LLM Configuration

Variable Description Default
OPENAI_API_KEY OpenAI API key for AI features -
OPENAI_BASE_URL Custom OpenAI API endpoint https://api.openai.com

Feature Flags

Variable Description Default
SHOW_DEMO_PROJECT Show demo project in UI False
ENABLE_BROWSER_MONITORING Enable browser monitoring True
ENABLE_FREETIER Enable free tier limitations False
ENABLE_REPLAY_SERVICE Enable session replay False

Logging

Variable Description Default Options
LOGGING_DESTINATION Where to send logs StdOut StdOut, GCP
LOG_LEVEL Logging level info trace, info, attention

Example Configurations

Minimal Development Setup

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/monoscope
BASIC_AUTH_ENABLED=True
BASIC_AUTH_USERNAME=admin
BASIC_AUTH_PASSWORD=changeme
API_KEY_ENCRYPTION_SECRET_KEY=monoscope123456monoscope1234567

Production with Auth0

DATABASE_URL=postgresql://prod_user:secure_pass@db.example.com:5432/monoscope?sslmode=require
ENVIRONMENT=PROD
HOST_URL=https://monoscope.example.com

# Disable basic auth
BASIC_AUTH_ENABLED=False

# Auth0 configuration
AUTH0_DOMAIN=example.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_SECRET=your-secret
AUTH0_CALLBACK=https://monoscope.example.com/auth_callback
AUTH0_LOGOUT_REDIRECT=https://monoscope.example.com

# Security
API_KEY_ENCRYPTION_SECRET_KEY=your-32-character-or-longer-secret-key

# Email notifications
SENDGRIDAPIKEY=your-sendgrid-key

High-Performance Configuration

# Increase batch processing
MESSAGES_PER_PUBSUB_PULL_BATCH=500
MAX_CONCURRENT_JOBS=16

# Optimize database connections
DATABASE_URL=postgresql://user:pass@localhost:5432/monoscope?pool_size=50

# Enable all performance features
ENABLE_BACKGROUND_JOBS=True
ENABLE_EVENTS_TABLE_UPDATES=True

Configuration Best Practices

  1. Use strong secrets: Generate random strings for API_KEY_ENCRYPTION_SECRET_KEY

    openssl rand -hex 32

  2. Secure database connections: Always use SSL in production

    DATABASE_URL=postgresql://...?sslmode=require

  3. Use .env files: Keep secrets out of docker-compose.yml

    # .env file
SENSITIVE_KEY=secret_value

# docker-compose.yml
environment:
  - SENSITIVE_KEY=${SENSITIVE_KEY}

  4. Set appropriate resource limits: Configure MAX_CONCURRENT_JOBS based on available CPU cores

  5. Enable only needed integrations: Don't configure unused notification services

Troubleshooting Configuration

Verify configuration is loaded

docker-compose exec monoscope env | grep MONOSCOPE

Check for configuration errors

docker-compose logs monoscope | grep -i error

Test database connection

docker-compose exec monoscope psql $DATABASE_URL -c "SELECT 1"