Configuration Guide
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"