Tutorial: Set Up an Internal Developer Forum With Discourse 3.0 and SSO 2.0 for 500 Engineers

version: '3.8'

services:
  discourse:
    image: discourse/base:3.0.0  # Pinned Discourse 3.0.0 image for reproducibility
    container_name: discourse_main
    environment:
      - DISCOURSE_HOSTNAME=forum.internal.dev  # Replace with your internal domain
      - DISCOURSE_DEVELOPER_EMAILS=admin@internal.dev  # Initial admin email
      - DISCOURSE_DB_HOST=postgres
      - DISCOURSE_DB_NAME=discourse_prod
      - DISCOURSE_DB_USERNAME=discourse
      - DISCOURSE_DB_PASSWORD=${DB_PASSWORD}  # Inject via .env file
      - DISCOURSE_REDIS_HOST=redis
      - DISCOURSE_REDIS_PORT=6379
      - DISCOURSE_SMTP_ADDRESS=smtp.internal.dev
      - DISCOURSE_SMTP_PORT=587
      - DISCOURSE_SMTP_USER_NAME=smtp_user
      - DISCOURSE_SMTP_PASSWORD=${SMTP_PASSWORD}
      - DISCOURSE_ENABLE_SSO=true
      - DISCOURSE_SSO2_PROVIDER_NAME=InternalSSO
      - DISCOURSE_SSO2_CLIENT_ID=${SSO_CLIENT_ID}
      - DISCOURSE_SSO2_CLIENT_SECRET=${SSO_CLIENT_SECRET}
      - DISCOURSE_SSO2_SCOPE=openid email profile
      - DISCOURSE_SSO2_AUTHORIZE_URL=https://sso.internal.dev/oauth2/authorize
      - DISCOURSE_SSO2_TOKEN_URL=https://sso.internal.dev/oauth2/token
      - DISCOURSE_SSO2_USER_INFO_URL=https://sso.internal.dev/oauth2/userinfo
      - DISCOURSE_MAX_CONCURRENT_USERS=500  # Tune for 500-engineer org
      - DISCOURSE_RATE_LIMIT_CREATE_TOPIC=10/minute  # Prevent spam
      - DISCOURSE_RATE_LIMIT_CREATE_POST=30/minute
    volumes:
      - discourse_data:/var/discourse/shared  # Persist uploads, backups
      - ./discourse-config:/etc/discourse  # Custom config overrides
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      postgres:
        condition: service_healthy  # Wait for DB to be ready
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/srv/status"]  # Check Discourse health
      interval: 30s
      timeout: 10s
      retries: 5
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine  # Supported PostgreSQL version for Discourse 3.0
    container_name: discourse_postgres
    environment:
      - POSTGRES_DB=discourse_prod
      - POSTGRES_USER=discourse
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U discourse -d discourse_prod"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7.2-alpine  # Redis 7.2+ required for Discourse 3.0
    container_name: discourse_redis
    command: redis-server --maxmemory 2gb --maxmemory-policy allkeys-lru  # Tune for 500 users
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  nginx:
    image: nginx:1.25-alpine
    container_name: discourse_nginx
    volumes:
      - ./nginx-conf:/etc/nginx/conf.d  # Custom Nginx config for SSL termination
      - ./ssl-certs:/etc/ssl/certs  # Internal CA certs for corporate domain
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - discourse
    restart: unless-stopped

volumes:
  discourse_data:
  postgres_data:
  redis_data:

import os
import requests
import json
from typing import Dict, Optional
import logging
from datetime import datetime

# Configure logging for audit trails
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s',
    handlers=[logging.FileHandler('discourse_sso_setup.log'), logging.StreamHandler()]
)
logger = logging.getLogger(__name__)

class DiscourseSSOConfigurator:
    \"\"\"Configures Discourse 3.0 SSO 2.0 settings via the admin API\"\"\"

    def __init__(self, discourse_url: str, admin_api_key: str, admin_user: str):
        self.discourse_url = discourse_url.rstrip('/')
        self.admin_api_key = admin_api_key
        self.admin_user = admin_user
        self.session = requests.Session()
        self.session.headers.update({
            'Api-Key': self.admin_api_key,
            'Api-Username': self.admin_user,
            'Content-Type': 'application/json'
        })
        # Disable SSL verification for internal corporate CAs (enable only in prod with valid certs)
        self.session.verify = False  # TODO: Replace with path to internal CA bundle in production
        logger.warning("SSL verification disabled for internal CA testing")

    def _make_request(self, method: str, endpoint: str, payload: Optional[Dict] = None) -> Dict:
        \"\"\"Wrapper for Discourse API requests with error handling\"\"\"
        url = f"{self.discourse_url}/admin{endpoint}"
        try:
            if method.upper() == 'GET':
                response = self.session.get(url, timeout=10)
            elif method.upper() == 'PUT':
                response = self.session.put(url, json=payload, timeout=10)
            else:
                raise ValueError(f"Unsupported method: {method}")

            response.raise_for_status()  # Raise HTTPError for 4xx/5xx responses
            return response.json()
        except requests.exceptions.Timeout:
            logger.error(f"Request to {url} timed out after 10s")
            raise
        except requests.exceptions.HTTPError as e:
            logger.error(f"HTTP error {e.response.status_code} for {url}: {e.response.text}")
            raise
        except requests.exceptions.ConnectionError:
            logger.error(f"Failed to connect to {url} - check Discourse is running")
            raise

    def enable_sso2(self, sso_config: Dict) -> bool:
        \"\"\"Enables SSO 2.0 with provided OIDC configuration\"\"\"
        required_keys = ['client_id', 'client_secret', 'authorize_url', 'token_url', 'user_info_url']
        missing_keys = [key for key in required_keys if key not in sso_config]
        if missing_keys:
            raise ValueError(f"Missing required SSO config keys: {missing_keys}")

        # Map SSO config to Discourse settings
        discourse_settings = {
            'enable_sso': True,
            'sso2_enabled': True,
            'sso2_provider_name': sso_config.get('provider_name', 'InternalSSO'),
            'sso2_client_id': sso_config['client_id'],
            'sso2_client_secret': sso_config['client_secret'],
            'sso2_scope': sso_config.get('scope', 'openid email profile'),
            'sso2_authorize_url': sso_config['authorize_url'],
            'sso2_token_url': sso_config['token_url'],
            'sso2_user_info_url': sso_config['user_info_url'],
            'sso2_callback_url': f"{self.discourse_url}/auth/sso2/callback",
            'sso2_auto_create_users': True,  # Auto-create users on first SSO login
            'sso2_require_valid_ip': False  # Disable for internal networks; enable with IP allowlists in prod
        }

        logger.info(f"Applying SSO 2.0 settings to Discourse at {self.discourse_url}")
        try:
            # Update site settings in batches (Discourse API requires per-setting updates)
            for setting_key, setting_value in discourse_settings.items():
                endpoint = f"/admin/site_settings/{setting_key}"
                payload = {'value': setting_value}
                self._make_request('PUT', endpoint, payload)
                logger.info(f"Set {setting_key} to {setting_value}")

            # Verify SSO is enabled
            verify_endpoint = "/admin/site_settings/enable_sso"
            verify_response = self._make_request('GET', verify_endpoint)
            if verify_response.get('value') is True:
                logger.info("SSO 2.0 enabled successfully")
                return True
            else:
                logger.error("SSO enable setting not applied correctly")
                return False
        except Exception as e:
            logger.error(f"Failed to enable SSO 2.0: {str(e)}")
            return False

    def validate_sso_flow(self, test_user_email: str) -> bool:
        \"\"\"Validates SSO 2.0 flow by checking user creation\"\"\"
        try:
            # Check if test user exists (auto-created on first login)
            endpoint = f"/admin/users/{test_user_email}.json"
            response = self._make_request('GET', endpoint)
            if response.get('user'):
                logger.info(f"Test user {test_user_email} found - SSO flow works")
                return True
            else:
                logger.warning(f"Test user {test_user_email} not found - trigger a test login first")
                return False
        except Exception as e:
            logger.error(f"SSO validation failed: {str(e)}")
            return False

if __name__ == "__main__":
    # Load config from environment variables (never hardcode secrets!)
    DISCOURSE_URL = os.getenv('DISCOURSE_URL', 'https://forum.internal.dev')
    ADMIN_API_KEY = os.getenv('DISCOURSE_ADMIN_API_KEY')
    ADMIN_USER = os.getenv('DISCOURSE_ADMIN_USER', 'admin')
    SSO_CLIENT_ID = os.getenv('SSO_CLIENT_ID')
    SSO_CLIENT_SECRET = os.getenv('SSO_CLIENT_SECRET')
    SSO_AUTHORIZE_URL = os.getenv('SSO_AUTHORIZE_URL', 'https://sso.internal.dev/oauth2/authorize')
    SSO_TOKEN_URL = os.getenv('SSO_TOKEN_URL', 'https://sso.internal.dev/oauth2/token')
    SSO_USER_INFO_URL = os.getenv('SSO_USER_INFO_URL', 'https://sso.internal.dev/oauth2/userinfo')
    TEST_USER_EMAIL = os.getenv('TEST_USER_EMAIL')

    # Validate required env vars
    required_vars = ['ADMIN_API_KEY', 'SSO_CLIENT_ID', 'SSO_CLIENT_SECRET']
    missing_vars = [var for var in required_vars if not os.getenv(var)]
    if missing_vars:
        logger.error(f"Missing required environment variables: {missing_vars}")
        exit(1)

    configurator = DiscourseSSOConfigurator(
        discourse_url=DISCOURSE_URL,
        admin_api_key=ADMIN_API_KEY,
        admin_user=ADMIN_USER
    )

    sso_config = {
        'client_id': SSO_CLIENT_ID,
        'client_secret': SSO_CLIENT_SECRET,
        'authorize_url': SSO_AUTHORIZE_URL,
        'token_url': SSO_TOKEN_URL,
        'user_info_url': SSO_USER_INFO_URL,
        'provider_name': 'InternalSSO'
    }

    logger.info(f"Starting SSO 2.0 setup for Discourse at {DISCOURSE_URL}")
    success = configurator.enable_sso2(sso_config)

    if success and TEST_USER_EMAIL:
        configurator.validate_sso_flow(TEST_USER_EMAIL)

    if success:
        logger.info("Discourse SSO 2.0 setup completed successfully")
        exit(0)
    else:
        logger.error("Discourse SSO 2.0 setup failed")
        exit(1)

import time
import random
from locust import HttpUser, task, between, events
import logging
from typing import Dict
import json
from datetime import datetime

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Discourse API endpoints for load testing
DISCOURSE_BASE = "https://forum.internal.dev"
SSO_LOGIN_URL = f"{DISCOURSE_BASE}/auth/sso2"
CATEGORY_ID = 2  # Replace with your internal "General Discussion" category ID

class DiscourseLoadTestUser(HttpUser):
    \"\"\"Simulates a Discourse user for 500-concurrent-engineer load testing\"\"\"
    wait_time = between(1, 5)  # Random wait between 1-5s between tasks, mimicking real user behavior
    sso_token = None
    user_email = None

    def on_start(self):
        \"\"\"Authenticate via SSO 2.0 on user start (simulates login)\"\"\"
        try:
            # In real testing, use a pool of pre-generated SSO tokens for 500 test users
            # For this example, we simulate SSO login with a test token
            test_user_id = random.randint(1, 500)
            self.user_email = f"loadtest.user{test_user_id}@internal.dev"

            # Simulate SSO token exchange (in practice, use real OIDC token from your SSO provider)
            self.sso_token = f"simulated_sso_token_{test_user_id}_{int(time.time())}"

            # Authenticate with Discourse using SSO token
            login_payload = {
                'sso_token': self.sso_token,
                'email': self.user_email
            }
            # Note: Discourse expects SSO callback, so this is a simplified simulation
            # For full flow, use Discourse's /auth/sso2/callback endpoint
            with self.client.post(
                "/login",
                data=login_payload,
                catch_response=True,
                headers={'Content-Type': 'application/x-www-form-urlencoded'}
            ) as response:
                if response.status_code == 200:
                    logger.info(f"User {self.user_email} logged in successfully")
                    response.success()
                else:
                    logger.error(f"Login failed for {self.user_email}: {response.status_code}")
                    response.failure(f"Login failed: {response.text}")
        except Exception as e:
            logger.error(f"On start error for user: {str(e)}")
            raise

    @task(3)  # 3x more likely to browse than post
    def browse_topics(self):
        \"\"\"Simulate browsing recent topics in the main category\"\"\"
        try:
            with self.client.get(
                f"/c/{CATEGORY_ID}.json",
                catch_response=True,
                headers={'Accept': 'application/json'}
            ) as response:
                if response.status_code == 200:
                    topics = response.json().get('topic_list', {}).get('topics', [])
                    if topics:
                        topic_id = random.choice(topics)['id']
                        # View a random topic from the list
                        self.client.get(f"/t/{topic_id}.json", catch_response=True)
                    response.success()
                else:
                    response.failure(f"Failed to fetch topics: {response.status_code}")
        except Exception as e:
            logger.error(f"Browse topics error: {str(e)}")

    @task(1)
    def create_post(self):
        \"\"\"Simulate creating a new post in a random topic\"\"\"
        try:
            # Fetch recent topics to post to
            with self.client.get(
                f"/c/{CATEGORY_ID}.json",
                catch_response=True,
                headers={'Accept': 'application/json'}
            ) as response:
                if response.status_code != 200:
                    response.failure(f"Failed to fetch topics for posting: {response.status_code}")
                    return
                topics = response.json().get('topic_list', {}).get('topics', [])
                if not topics:
                    response.failure("No topics found to post to")
                    return
                target_topic = random.choice(topics)
                topic_id = target_topic['id']
                topic_slug = target_topic['slug']

            # Create post payload
            post_payload = {
                'topic_id': topic_id,
                'raw': f"Load test post from {self.user_email} at {datetime.now().isoformat()}",
                'reply_to_post_number': None
            }

            # Send post request
            with self.client.post(
                "/posts.json",
                json=post_payload,
                catch_response=True,
                headers={'Accept': 'application/json'}
            ) as response:
                if response.status_code == 200:
                    logger.info(f"User {self.user_email} created post in topic {topic_id}")
                    response.success()
                else:
                    response.failure(f"Failed to create post: {response.status_code} - {response.text}")
        except Exception as e:
            logger.error(f"Create post error: {str(e)}")

    @task(1)
    def search_forum(self):
        \"\"\"Simulate searching the forum for common terms\"\"\"
        search_terms = ['api', 'deploy', 'onboarding', 'legacy', 'bug']
        term = random.choice(search_terms)
        try:
            with self.client.get(
                f"/search.json?q={term}",
                catch_response=True,
                headers={'Accept': 'application/json'}
            ) as response:
                if response.status_code == 200:
                    response.success()
                else:
                    response.failure(f"Search failed for term {term}: {response.status_code}")
        except Exception as e:
            logger.error(f"Search error: {str(e)}")

    def on_stop(self):
        \"\"\"Cleanup on user stop\"\"\"
        logger.info(f"User {self.user_email} stopped load test")
        self.sso_token = None
        self.user_email = None

@events.test_start.add_listener
def on_test_start(environment, **kwargs):
    logger.info(f"Starting Discourse load test with {environment.runner.target_user_count} users")

@events.test_stop.add_listener
def on_test_stop(environment, **kwargs):
    # Calculate aggregate stats
    stats = environment.runner.stats.total
    logger.info(f"Load test completed. Total requests: {stats.num_requests}")
    logger.info(f"Failed requests: {stats.num_failures}")
    logger.info(f"Average response time: {stats.avg_response_time}ms")
    logger.info(f"95th percentile response time: {stats.get_response_time_percentile(0.95)}ms")
    # Fail test if >1% requests fail or p95 > 500ms
    if stats.num_failures / stats.num_requests > 0.01:
        logger.error("Load test failed: >1% request failure rate")
        environment.runner.quit()
    if stats.get_response_time_percentile(0.95) > 500:
        logger.error("Load test failed: p95 response time > 500ms")
        environment.runner.quit()

# pgbouncer.ini snippet for Discourse connection pooling
[databases]
discourse_prod = host=postgres port=5432 dbname=discourse_prod user=discourse password=${DB_PASSWORD}

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 1000  # Support 500 Discourse users + overhead
default_pool_size = 50  # Match PostgreSQL's max_connections
server_lifetime = 3600

# Terraform ECS task definition snippet for Discourse 3.0
resource "aws_ecs_task_definition" "discourse" {
  family                   = "discourse-3-0"
  network_mode             = "awsvpc"
  requires_compatibilities = ["FARGATE"]
  cpu                      = "2048"  # 2 vCPU for 500 concurrent users
  memory                   = "4096"  # 4GB RAM

  container_definitions = jsonencode([{
    name      = "discourse"
    image     = "discourse/base:3.0.0"
    essential = true
    portMappings = [{
      containerPort = 80
      hostPort     = 80
      protocol     = "tcp"
    }]
    environment = [
      { name = "DISCOURSE_HOSTNAME", value = "forum.internal.dev" },
      { name = "DISCOURSE_MAX_CONCURRENT_USERS", value = "500" }
    ]
    secrets = [
      { name = "DISCOURSE_DB_PASSWORD", valueFrom = "arn:aws:secretsmanager:us-east-1:123456789012:secret:discourse-db-password" },
      { name = "DISCOURSE_SSO_CLIENT_SECRET", valueFrom = "arn:aws:secretsmanager:us-east-1:123456789012:secret:discourse-sso-secret" }
    ]
  }])
}

# Prometheus scrape config for Discourse 3.0 metrics
scrape_configs:
  - job_name: 'discourse'
    scrape_interval: 15s
    metrics_path: '/srv/status'
    static_configs:
      - targets: ['forum.internal.dev:80']
    params:
      format: ['prometheus']  # Discourse 3.0 supports Prometheus format natively

500-engineer-forum-setup/
├── docker/                  # Docker Compose and config files
│   ├── docker-compose.yml   # Discourse 3.0 full stack config (first code example)
│   ├── discourse-config/    # Custom Discourse site settings
│   ├── nginx-conf/          # Nginx SSL termination config
│   └── ssl-certs/           # Internal CA certs
├── sso-config/              # SSO 2.0 setup scripts
│   ├── discourse_sso_configurator.py  # Second code example (Python SSO configurator)
│   └── .env.example         # Environment variable template
├── load-testing/            # Locust load test scripts
│   └── locustfile.py        # Third code example (500-user load test)
├── terraform/               # Infrastructure as Code
│   ├── ecs.tf               # ECS task definition (from Developer Tip 2)
│   └── variables.tf         # Terraform variables
├── monitoring/              # Prometheus/Grafana config
│   ├── prometheus.yml       # Scrape config (from Developer Tip 3)
│   └── grafana-dashboard.json  # Pre-built Discourse dashboard
└── README.md                # Full setup instructions