Configuration Reference

This document provides a comprehensive reference for configuring Shugur Relay.

Configuration Sources

Shugur Relay uses YAML configuration files with support for multiple configuration sources. Configuration is loaded in the following order (later sources override earlier ones):

1. Embedded defaults - Built-in default values
2. Configuration file - YAML file specified with --config or config.yaml in current directory
3. Environment variables - Prefixed with SHUGUR_ (e.g., SHUGUR_RELAY_NAME)
4. Command line flags - CLI arguments override all other sources

Configuration File Format

The configuration follows a hierarchical YAML structure with these main sections:

• GENERAL - General application settings (reserved for future use)
• LOGGING - Logging configuration
• METRICS - Metrics and monitoring settings
• RELAY - Core relay functionality settings
• RELAY_POLICY - Access control and policy settings
• DATABASE - Database connection settings

LOGGING

Controls the logging output of the relay.

Log Levels

• debug - Detailed debugging information
• info - General information about relay operation
• warn - Warning messages for potential issues
• error - Error messages for failed operations
• fatal - Fatal errors that cause the relay to exit

Log Formats

• console - Human-readable colored output (good for development)
• json - Structured JSON output for log aggregation (recommended for production)

METRICS

Prometheus metrics collection and monitoring.

When enabled, metrics are exposed at http://localhost:2112/metrics in Prometheus format for monitoring relay performance, connections, and event processing.

DATABASE

Database connection configuration. Supports both CockroachDB (recommended) and PostgreSQL.

Supported Databases

• CockroachDB (recommended for production) - Provides distributed SQL with horizontal scaling
• PostgreSQL (compatible alternative) - Traditional relational database option

Connection Details

The relay automatically constructs the connection string using the server and port configuration with database name shugur_relay and optimized connection parameters. For production deployments, ensure proper certificates are in place for secure connections.

RELAY

Core relay configuration parameters.

Address Formats

• :8080 - Listen on all interfaces, port 8080
• localhost:8080 - Listen only on localhost
• 192.168.1.10:8080 - Listen on specific IP address

Timeout Formats

• 60s - 60 seconds
• 5m - 5 minutes
• 1h - 1 hour

Throttling

Rate Limiting

Rate Limiting Behavior

• Token Bucket Algorithm: Uses token bucket for smooth rate limiting
• Burst Allowance: Allows brief bursts above the steady rate
• Progressive Banning: Ban duration increases with repeated violations
• IP-based: Rate limits are applied per client IP address

RELAY_POLICY

Access control and content policies.

Blacklist

Whitelist

Access Control

• Blacklist: Explicitly deny these pubkeys from publishing events
• Whitelist: If non-empty, only allow these pubkeys to publish events
• Format: Use lowercase hex format without 0x prefix

Example:

RELAY_POLICY:
  BLACKLIST:
    PUBKEYS:
      - "abcd1234567890abcd1234567890abcd1234567890abcd1234567890abcd1234"
  WHITELIST:
    PUBKEYS:
      - "1234567890abcd1234567890abcd1234567890abcd1234567890abcd12345678"

Environment Variables

All configuration options can be set via environment variables using the SHUGUR_ prefix and underscores for nested values:

# Relay configuration
export SHUGUR_RELAY_NAME="my-relay"
export SHUGUR_RELAY_WS_ADDR=":8080"
export SHUGUR_RELAY_DESCRIPTION="My awesome relay"

# Database configuration
export SHUGUR_DATABASE_SERVER="db.example.com"
export SHUGUR_DATABASE_PORT="26257"

# Logging configuration
export SHUGUR_LOGGING_LEVEL="info"
export SHUGUR_LOGGING_FORMAT="json"
export SHUGUR_LOGGING_FILE="/var/log/relay.log"

# Metrics configuration
export SHUGUR_METRICS_ENABLED="true"
export SHUGUR_METRICS_PORT="2112"

# Rate limiting
export SHUGUR_RELAY_THROTTLING_RATE_LIMIT_ENABLED="true"
export SHUGUR_RELAY_THROTTLING_RATE_LIMIT_MAX_EVENTS_PER_SECOND="100"

Command Line Flags

Key configuration options can be overridden via command line flags:

./bin/relay start \
  --config /path/to/config.yaml \
  --relay-name "My Relay" \
  --db-host localhost \
  --db-port 26257 \
  --log-level info \
  --log-format json \
  --metrics-port 2112

Available Flags

• --config, -c - Path to configuration file
• --relay-name - Relay name
• --db-host - Database hostname
• --db-port - Database port
• --log-level - Logging level
• --log-file - Log file path
• --log-format - Log format
• --metrics-port - Metrics server port

Configuration Examples

Development Configuration

LOGGING:
  LEVEL: debug
  FORMAT: console

RELAY:
  NAME: "dev-relay"
  WS_ADDR: ":8080"
  THROTTLING:
    MAX_CONNECTIONS: 100
    RATE_LIMIT:
      ENABLED: false

DATABASE:
  SERVER: "localhost"
  PORT: 26257

Production Configuration

LOGGING:
  LEVEL: info
  FORMAT: json
  FILE: "/var/log/shugur-relay/relay.log"
  MAX_SIZE: 100
  MAX_BACKUPS: 30
  MAX_AGE: 30

METRICS:
  ENABLED: true
  PORT: 2112

RELAY:
  NAME: "production-relay"
  DESCRIPTION: "High-performance Nostr relay"
  CONTACT: "admin@example.com"
  WS_ADDR: ":8080"
  PUBLIC_URL: "wss://relay.example.com"
  THROTTLING:
    MAX_CONNECTIONS: 10000
    MAX_CONTENT_LENGTH: 4096
    RATE_LIMIT:
      ENABLED: true
      MAX_EVENTS_PER_SECOND: 50
      MAX_REQUESTS_PER_SECOND: 100
      PROGRESSIVE_BAN: true
      MAX_BAN_DURATION: 24h

DATABASE:
  SERVER: "prod-db-cluster.example.com"
  PORT: 26257

High-Security Configuration

RELAY_POLICY:
  WHITELIST:
    PUBKEYS:
      - "authorized_pubkey_1_here"
      - "authorized_pubkey_2_here"

RELAY:
  THROTTLING:
    MAX_CONTENT_LENGTH: 1024
    MAX_CONNECTIONS: 500
    BAN_THRESHOLD: 3
    BAN_DURATION: 60
    RATE_LIMIT:
      ENABLED: true
      MAX_EVENTS_PER_SECOND: 10
      MAX_REQUESTS_PER_SECOND: 20
      PROGRESSIVE_BAN: true

Configuration Validation

The relay validates configuration on startup and will exit with an error if:

• Required fields are missing
• Values are outside valid ranges
• URLs are malformed
• Email addresses are invalid (if provided)
• Time durations are invalid

Common Validation Errors

• Relay name too long: Must be 30 characters or less
• Description too long: Must be 200 characters or less
• Invalid email: Contact must be a valid email address
• Invalid URL: Icon, banner, and public URL must be valid URLs
• Invalid address: WebSocket address must be in correct format
• Invalid timeout: Timeouts must be positive durations

Performance Tuning

Connection Limits

RELAY:
  THROTTLING:
    MAX_CONNECTIONS: 10000       # Adjust based on server capacity

Memory Usage

RELAY:
  EVENT_CACHE_SIZE: 50000        # Increase for better performance
  SEND_BUFFER_SIZE: 16384        # Increase for high-throughput scenarios

Rate Limiting

RELAY:
  THROTTLING:
    RATE_LIMIT:
      MAX_EVENTS_PER_SECOND: 100  # Higher limits for trusted environments
      BURST_SIZE: 50               # Allow larger bursts

Security Considerations

Network Security

• Use TLS/SSL in production (configure reverse proxy)
• Consider firewall rules for database access
• Monitor unusual traffic patterns

Access Control

• Use whitelist for private relays
• Regularly review blacklisted pubkeys
• Monitor for abuse patterns

Logging Security

• Avoid logging sensitive information
• Secure log files with appropriate permissions
• Consider log rotation and retention policies

Troubleshooting Configuration

Configuration Not Loading

1. Check file path and permissions
2. Validate YAML syntax
3. Check environment variable names
4. Review startup logs for validation errors

Performance Issues

1. Adjust connection limits
2. Increase cache sizes
3. Review rate limiting settings
4. Monitor database performance

Security Issues

1. Review access control settings
2. Check rate limiting configuration
3. Monitor for banned IPs
4. Review event validation settings