Configuration Guide

November 23, 2025 · View on GitHub

This guide covers all configuration options for Monoscope.

Configuration Methods

Monoscope can be configured through:

Environment variables (recommended)
.env file
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

Use strong secrets: Generate random strings for API_KEY_ENCRYPTION_SECRET_KEY
```
openssl rand -hex 32
```
Secure database connections: Always use SSL in production
```
DATABASE_URL=postgresql://...?sslmode=require
```

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

# .env file
SENSITIVE_KEY=secret_value

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

Set appropriate resource limits: Configure MAX_CONCURRENT_JOBS based on available CPU cores
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"