pgSentinelConfiguration

Complete configuration guide for pgSentinel monitoring platform. Environment variables, Docker settings, and customization options.

Environment variables

Docker configuration

Production ready

Environment Variables

Complete reference for all configuration options

Database Configuration

DATABASE_URLRequired

PostgreSQL connection string

Example

DATABASE_URL=postgresql://username:password@localhost:5432/database

Default

DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres

DB_HOSTOptional

PostgreSQL host (overrides DATABASE_URL)

Example

DB_HOST=localhost

Default

DB_HOST=localhost

DB_PORTOptional

PostgreSQL port (overrides DATABASE_URL)

Example

DB_PORT=5432

Default

DB_PORT=5432

DB_NAMEOptional

PostgreSQL database name (overrides DATABASE_URL)

Example

DB_NAME=postgres

Default

DB_NAME=postgres

DB_USEROptional

PostgreSQL username (overrides DATABASE_URL)

Example

DB_USER=postgres

Default

DB_USER=postgres

DB_PASSWORDOptional

PostgreSQL password (overrides DATABASE_URL)

Example

DB_PASSWORD=password

Default

DB_PASSWORD=password

Redis Configuration

REDIS_URLRequired

Redis connection string for caching

Example

REDIS_URL=redis://localhost:6379

Default

REDIS_URL=redis://localhost:6379

REDIS_HOSTOptional

Redis host (overrides REDIS_URL)

Example

REDIS_HOST=localhost

Default

REDIS_HOST=localhost

REDIS_PORTOptional

Redis port (overrides REDIS_URL)

Example

REDIS_PORT=6379

Default

REDIS_PORT=6379

REDIS_PASSWORDOptional

Redis password for authentication

Example

REDIS_PASSWORD=redis_password

Default

REDIS_PASSWORD=

Service Ports

BACKEND_PORTOptional

Backend API server port

Example

BACKEND_PORT=8000

Default

BACKEND_PORT=8000

FRONTEND_PORTOptional

Frontend web server port

Example

FRONTEND_PORT=3000

Default

FRONTEND_PORT=3000

WEBSITE_PORTOptional

Marketing website port

Example

WEBSITE_PORT=3002

Default

WEBSITE_PORT=3002

PROMETHEUS_PORTOptional

Prometheus metrics server port

Example

PROMETHEUS_PORT=9090

Default

PROMETHEUS_PORT=9090

GRAFANA_PORTOptional

Grafana dashboard port

Example

GRAFANA_PORT=3001

Default

GRAFANA_PORT=3001

Monitoring Configuration

METRICS_INTERVALOptional

Metrics collection interval in seconds

Example

METRICS_INTERVAL=5

Default

METRICS_INTERVAL=5

PROMETHEUS_RETENTIONOptional

Prometheus data retention period

Example

PROMETHEUS_RETENTION=15d

Default

PROMETHEUS_RETENTION=15d

GRAFANA_ADMIN_PASSWORDOptional

Grafana admin password

Example

GRAFANA_ADMIN_PASSWORD=admin123

Default

GRAFANA_ADMIN_PASSWORD=admin

ALERT_EMAILOptional

Email address for alerts

Example

ALERT_EMAIL=admin@example.com

Default

ALERT_EMAIL=

Security & Authentication

SECRET_KEYRequired

Secret key for JWT token signing

Example

SECRET_KEY=your-secret-key-here

Default

SECRET_KEY=change-this-secret-key

JWT_EXPIRE_HOURSOptional

JWT token expiration time in hours

Example

JWT_EXPIRE_HOURS=24

Default

JWT_EXPIRE_HOURS=24

CORS_ORIGINSOptional

Allowed CORS origins (comma-separated)

Example

CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

Default

CORS_ORIGINS=http://localhost:3000

Docker Configurations

Docker Compose setups for different environments

Docker Compose Override

Override default settings using docker-compose.override.yml

# docker-compose.override.yml
version: '3.8'

services:
  backend:
    environment:
      - DATABASE_URL=postgresql://user:pass@host:5432/db
      - REDIS_URL=redis://redis:6379
      - METRICS_INTERVAL=10
    ports:
      - "8000:8000"
  
  frontend:
    environment:
      - NEXT_PUBLIC_API_URL=http://localhost:8000
    ports:
      - "3000:3000"
  
  grafana:
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=your-password
    ports:
      - "3001:3000"
  
  prometheus:
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.retention.time=30d'
    ports:
      - "9090:9090"

Environment File

Create .env file for local development

# .env
# Database Configuration
DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=postgres
DB_USER=postgres
DB_PASSWORD=password

# Redis Configuration
REDIS_URL=redis://localhost:6379
REDIS_HOST=localhost
REDIS_PORT=6379

# Service Ports
BACKEND_PORT=8000
FRONTEND_PORT=3000
WEBSITE_PORT=3002
PROMETHEUS_PORT=9090
GRAFANA_PORT=3001

# Monitoring Configuration
METRICS_INTERVAL=5
PROMETHEUS_RETENTION=15d
GRAFANA_ADMIN_PASSWORD=admin123
ALERT_EMAIL=admin@example.com

# Security
SECRET_KEY=your-super-secret-key-here
JWT_EXPIRE_HOURS=24
CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

Production Docker Compose

Production-ready configuration with external services

# docker-compose.prod.yml
version: '3.8'

services:
  backend:
    image: pgsentinel/backend:latest
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - SECRET_KEY=${SECRET_KEY}
      - METRICS_INTERVAL=30
    restart: unless-stopped
    depends_on:
      - postgres
      - redis
  
  frontend:
    image: pgsentinel/frontend:latest
    environment:
      - NEXT_PUBLIC_API_URL=${API_URL}
    restart: unless-stopped
    depends_on:
      - backend
  
  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=${DB_NAME}
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
  
  redis:
    image: redis:7-alpine
    restart: unless-stopped
  
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./monitoring/prometheus:/etc/prometheus
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.retention.time=30d'
      - '--web.console.libraries=/etc/prometheus/console_libraries'
      - '--web.console.templates=/etc/prometheus/consoles'
    restart: unless-stopped
  
  grafana:
    image: grafana/grafana:latest
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
      - ./monitoring/grafana:/etc/grafana/provisioning
    restart: unless-stopped

volumes:
  postgres_data:
  prometheus_data:
  grafana_data:

PostgreSQL Configuration

Required PostgreSQL setup for optimal monitoring

Required Extensions

Enable these PostgreSQL extensions for full functionality

-- Connect to your PostgreSQL database
psql -U postgres -d your_database

-- Enable required extensions
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS pg_stat_kcache;
CREATE EXTENSION IF NOT EXISTS pg_qualstats;
CREATE EXTENSION IF NOT EXISTS pg_buffercache;

-- Grant necessary permissions
GRANT pg_monitor TO your_api_user;
GRANT SELECT ON pg_stat_statements TO your_api_user;
GRANT SELECT ON pg_stat_user_tables TO your_api_user;
GRANT SELECT ON pg_stat_user_indexes TO your_api_user;
GRANT SELECT ON pg_stat_database TO your_api_user;
GRANT SELECT ON pg_stat_activity TO your_api_user;
GRANT SELECT ON pg_locks TO your_api_user;
GRANT SELECT ON pg_stat_replication TO your_api_user;

postgresql.conf Settings

Recommended PostgreSQL configuration for optimal monitoring

# postgresql.conf
# Shared preload libraries
shared_preload_libraries = 'pg_stat_statements'

# pg_stat_statements configuration
pg_stat_statements.max = 10000
pg_stat_statements.track = all
pg_stat_statements.track_utility = on
pg_stat_statements.track_planning = on

# Logging configuration
log_destination = 'stderr'
logging_collector = on
log_directory = 'log'
log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'
log_rotation_age = 1d
log_rotation_size = 100MB
log_min_duration_statement = 1000  # Log slow queries (1 second)

# Statistics configuration
track_activities = on
track_counts = on
track_io_timing = on
track_functions = all

# Connection settings
max_connections = 100
shared_buffers = 256MB
effective_cache_size = 1GB

# WAL settings
wal_level = replica
max_wal_senders = 3
max_replication_slots = 3

Customization Options

Extend and customize pgSentinel for your needs

Custom Metrics

Add your own custom metrics to the monitoring system

You can add custom metrics by extending the Prometheus metrics in the backend:

# In backend/main.py

from prometheus_client import Counter, Gauge, Histogram

# Add custom metrics

custom_metric = Counter('custom_operations_total', 'Total custom operations')

custom_gauge = Gauge('custom_value', 'Custom value metric')

Custom Dashboards

Create custom Grafana dashboards for specific use cases

Add custom dashboard JSON files to the monitoring/grafana/dashboards/ directory:

# Directory structure

monitoring/

├── grafana/

│ ├── dashboards/

│ │ ├── custom-dashboard.json

│ │ └── business-metrics.json

│ └── provisioning/

Alert Rules

Configure custom alert rules for your specific requirements

Modify the Prometheus alert rules in monitoring/prometheus/alerts.yml:

# Custom alert rule example

- alert: CustomHighCPU

expr: cpu_usage_percent > 90

for: 5m

labels:

severity: warning

annotations:

summary: "High CPU usage detected"

Configuration Validation

Verify your configuration is correct

Health Check

Verify all services are running correctly

curl http://localhost:8000/api/v1/health

Database Connection

Test PostgreSQL connectivity and permissions

curl http://localhost:8000/api/v1/insights/dashboard

Metrics Collection

Verify metrics are being collected and stored

curl http://localhost:9090/api/v1/query?query=up

Need Help?

If you're having trouble with configuration, check our troubleshooting guide or get support.

Troubleshooting

Common issues and solutions

API Reference

Complete API documentation