Skip to content

Configuration

Jump to bottom
Hunter edited this page Jan 15, 2026 · 1 revision

Configuration Reference

Reference for all configuration options in the Wisp Framework.

See also: Deployment-Guide | Troubleshooting | Architecture-Overview

Table of Contents

Environment Variables

Configuration is loaded from environment variables and optional .env files.

Required Variables

DISCORD_TOKEN

Discord bot token. Required.

DISCORD_TOKEN=your_bot_token_here

Optional Variables

ENV

Environment name. Determines which .env.{ENV} file to load. Default: local

ENV=production

DATABASE_URL

PostgreSQL database connection URL. Optional (requires [db] extra).

DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/discord_bot

⚠️ SECURITY WARNING: Change default passwords from docker-compose.yml before production!

REDIS_URL

Redis connection URL. Optional (requires [redis] extra).

REDIS_URL=redis://localhost:6379/0

LOG_LEVEL

Logging level. Default: INFO

Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL

LOG_LEVEL=DEBUG

SYNC_ON_STARTUP

Whether to sync slash commands on startup. Default: true

SYNC_ON_STARTUP=false

OWNER_ID

Discord user ID of the bot owner. Used for owner-only commands.

OWNER_ID=123456789012345678

WELCOME_CHANNEL_ID

Default welcome channel ID for guilds.

WELCOME_CHANNEL_ID=987654321098765432

Discord Intent Configuration

Configure Discord gateway intents via environment variables. All default to true if not specified.

INTENTS_GUILDS

Guilds intent. Default: true

INTENTS_GUILDS=true

INTENTS_MEMBERS

Members intent. Default: true

INTENTS_MEMBERS=true

INTENTS_MESSAGES

Messages intent. Default: true

INTENTS_MESSAGES=true

INTENTS_MESSAGE_CONTENT

Message content intent. Default: true

INTENTS_MESSAGE_CONTENT=true

INTENTS_REACTIONS

Reactions intent. Default: true

INTENTS_REACTIONS=true

INTENTS_VOICE_STATES

Voice states intent. Default: true

INTENTS_VOICE_STATES=true

INTENTS_GUILD_MESSAGES

Guild messages intent. Default: true

INTENTS_GUILD_MESSAGES=true

INTENTS_DM_MESSAGES

DM messages intent. Default: true

INTENTS_DM_MESSAGES=true

Database Configuration

DB_POOL_SIZE

Database connection pool size. Default: 10

DB_POOL_SIZE=20

DB_MAX_OVERFLOW

Maximum overflow connections. Default: 20

DB_MAX_OVERFLOW=30

DB_POOL_TIMEOUT

Connection pool timeout in seconds. Default: 30

DB_POOL_TIMEOUT=60

Docker Compose Variables

When using Docker Compose, these variables configure the database:

POSTGRES_USER

PostgreSQL username. Default (dev): discord_bot

POSTGRES_USER=myuser

POSTGRES_PASSWORD

PostgreSQL password. MUST be changed in production!

POSTGRES_PASSWORD=strong_password_here

POSTGRES_DB

PostgreSQL database name. Default (dev): discord_bot

POSTGRES_DB=mydb

Configuration Loading

Environment File Loading

The framework loads environment variables from .env.{ENV} files:

  1. Check ENV environment variable (default: local)
  2. Load .env.{ENV} file if it exists
  3. Environment variables override file values

Example .env.local 

# Discord Configuration
DISCORD_TOKEN=your_token_here
OWNER_ID=123456789012345678

# Database Configuration
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/discord_bot

# Redis Configuration
REDIS_URL=redis://localhost:6379/0

# Logging
LOG_LEVEL=INFO

# Intents
INTENTS_GUILDS=true
INTENTS_MEMBERS=true
INTENTS_MESSAGES=true
INTENTS_MESSAGE_CONTENT=true

Example .env.prod 

# Discord Configuration
DISCORD_TOKEN=${DISCORD_TOKEN}
OWNER_ID=${OWNER_ID}

# Database Configuration (use environment variables, never defaults!)
DATABASE_URL=${DATABASE_URL}
POSTGRES_USER=${POSTGRES_USER}
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
POSTGRES_DB=${POSTGRES_DB}

# Logging
LOG_LEVEL=WARNING

# Intents (only enable what you need)
INTENTS_GUILDS=true
INTENTS_MEMBERS=true
INTENTS_MESSAGES=false
INTENTS_MESSAGE_CONTENT=false

Discord Intents

Required Intents

Depending on your bot's functionality, you may need specific intents:

  • Guilds: Required for most bots
  • Members: Required for member join/leave events
  • Messages: Required for message events
  • Message Content: Required to read message content
  • Reactions: Required for reaction events
  • Voice States: Required for voice channel events

Enabling Intents in Discord Developer Portal

  1. Go to Discord Developer Portal
  2. Select your application
  3. Go to "Bot" section
  4. Scroll to "Privileged Gateway Intents"
  5. Enable required intents
  6. Save changes

Database Configuration

Connection URL Format

postgresql+asyncpg://[user[:password]@][host][:port][/database]

Examples

# Local database
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/discord_bot

# Remote database
DATABASE_URL=postgresql+asyncpg://user:password@db.example.com:5432/discord_bot

# With SSL
DATABASE_URL=postgresql+asyncpg://user:password@db.example.com:5432/discord_bot?ssl=require

Connection Pooling

The framework uses SQLAlchemy's connection pooling:

  • Pool Size: Number of connections to maintain
  • Max Overflow: Additional connections allowed beyond pool size
  • Pool Timeout: Time to wait for a connection before timing out

Redis Configuration

Connection URL Format

redis://[password@]host[:port][/database]

Examples

# Local Redis
REDIS_URL=redis://localhost:6379/0

# Remote Redis with password
REDIS_URL=redis://password@redis.example.com:6379/0

# Redis Cluster
REDIS_URL=redis://node1:6379,node2:6379,node3:6379

Logging Configuration

Log Levels

  • DEBUG: Detailed information for debugging
  • INFO: General informational messages
  • WARNING: Warning messages
  • ERROR: Error messages
  • CRITICAL: Critical errors

Structured Logging

The framework uses structured logging with correlation IDs:

import logging

logger = logging.getLogger(__name__)
logger.info("Message", extra={"key": "value"})

Service Configuration

Health Service

No configuration required. Automatically checks all services.

Cache Service

Automatically uses Redis if REDIS_URL is set, otherwise uses in-memory cache.

Metrics Service

No configuration required. Metrics are stored in memory.

Scheduler Service

No configuration required. Tasks are scheduled in memory.

Audit Service

Logs to Python's logging system. Configure via LOG_LEVEL.

Webhook Logger Service

Configure webhook URL via environment variable (if implemented).

Database Service

Configured via DATABASE_URL and database-specific environment variables.

Configuration Validation

The framework validates configuration on startup:

  • Required Variables: DISCORD_TOKEN must be present
  • Format Validation: URLs and IDs are validated
  • Service Availability: Services check for required dependencies

Error Handling

If configuration is invalid:

from wisp_framework.config import ConfigError

try:
    config = AppConfig()
except ConfigError as e:
    print(f"Configuration error: {e}")

Best Practices

  1. Use Environment Variables: Never hardcode sensitive values
  2. Separate Environments: Use different .env files for dev/prod
  3. Change Defaults: Always change default passwords
  4. Minimal Intents: Only enable intents you need
  5. Secure Storage: Store production secrets securely
  6. Validate Early: Check configuration before deployment
  7. Document Custom Config: Document any custom configuration

Next Steps

Clone this wiki locally