Skip to content
Klutch.sh Docs

Deploying a Discourse Forum

Introduction

Discourse is a modern, feature-rich, open-source discussion platform designed for civilized online communities. Built with Ruby on Rails and Ember.js, Discourse provides a powerful alternative to traditional forums with real-time updates, rich media embedding, comprehensive moderation tools, and mobile-responsive design. Whether you’re building a community for customers, developers, enthusiasts, or any other group, Discourse offers the tools needed to foster meaningful discussions and engagement.

Discourse stands out with its:

  • Modern Interface: Clean, responsive design that works seamlessly on desktop and mobile devices
  • Real-Time Updates: Live notifications, instant replies, and dynamic content loading
  • Powerful Moderation: Advanced moderation tools, trust levels, and community management features
  • Rich Content: Support for images, videos, code blocks, polls, and external media embedding
  • Extensive Plugins: Large ecosystem of plugins and themes for customization
  • SSO Integration: Single sign-on support for seamless authentication
  • Email Integration: Full email support for notifications and posting via email
  • Search & Discovery: Fast full-text search, categorization, and tagging systems
  • Gamification: Badges, trust levels, and achievements to encourage engagement

This comprehensive guide walks you through deploying Discourse on Klutch.sh using Docker, covering installation steps, database configuration, persistent storage setup, environment variables, and production best practices.

Prerequisites

Before you begin deploying Discourse, ensure you have the following:

  • A Klutch.sh account
  • A GitHub account with a repository for your Discourse project
  • Docker installed locally for testing (optional but recommended)
  • Basic understanding of Docker, PostgreSQL, Redis, and Ruby applications
  • A domain name for your Discourse forum (recommended for production)

Understanding Discourse Architecture

Before deployment, it’s important to understand Discourse’s architecture:

  • Application Server: Ruby on Rails application serving the API and frontend
  • PostgreSQL Database: Primary data store for all content, users, and configuration
  • Redis: In-memory cache for sessions, job queues, and caching
  • Sidekiq: Background job processor for emails, notifications, and maintenance tasks
  • Nginx (optional): Reverse proxy for serving static assets and SSL termination

For Klutch.sh deployment, we’ll containerize Discourse with its dependencies, utilizing persistent volumes for data storage and external databases when needed.

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Discourse deployment project:

Terminal window
mkdir discourse-klutch
cd discourse-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root. This example uses the official Discourse Docker image as a base:

FROM discourse/base:2.0.20231030-0205


# Set working directory
WORKDIR /var/www/discourse


# Environment variables (override these in Klutch.sh dashboard)
ENV RAILS_ENV=production
ENV RUBY_GLOBAL_METHOD_CACHE_SIZE=131072
ENV RUBY_GC_HEAP_GROWTH_MAX_SLOTS=40000
ENV RUBY_GC_HEAP_INIT_SLOTS=400000
ENV RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR=1.5


# Clone Discourse (use specific version for production)
RUN git clone https://github.com/discourse/discourse.git /var/www/discourse && \
    cd /var/www/discourse && \
    git checkout v3.1.3


# Install dependencies
RUN bundle install --deployment --without test development && \
    yarn install --production --frozen-lockfile


# Precompile assets (optional, can be done at runtime)
# RUN bundle exec rake assets:precompile


# Create necessary directories
RUN mkdir -p /shared/log /shared/uploads /shared/backups


# Expose Discourse port
EXPOSE 3000


# Copy entrypoint script
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh


ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000"]

Note: This Dockerfile uses a specific Discourse version (v3.1.3). Check the Discourse releases page for the latest stable version.

Step 3: Create the Entrypoint Script

Create a docker-entrypoint.sh script to handle database migrations and initialization:

#!/bin/bash
set -e


echo "Starting Discourse initialization..."


# Wait for PostgreSQL to be ready
until PGPASSWORD=$DISCOURSE_DB_PASSWORD psql -h "$DISCOURSE_DB_HOST" -U "$DISCOURSE_DB_USERNAME" -d "$DISCOURSE_DB_NAME" -c '\q' 2>/dev/null; do
  echo "Waiting for PostgreSQL..."
  sleep 2
done


echo "PostgreSQL is ready!"


# Wait for Redis to be ready
until redis-cli -h "$DISCOURSE_REDIS_HOST" -p "${DISCOURSE_REDIS_PORT:-6379}" ping 2>/dev/null; do
  echo "Waiting for Redis..."
  sleep 2
done


echo "Redis is ready!"


# Run database migrations
echo "Running database migrations..."
bundle exec rake db:migrate


# Precompile assets if not done at build time
if [ ! -f "/var/www/discourse/public/assets/.sprockets-manifest-*.json" ]; then
  echo "Precompiling assets..."
  bundle exec rake assets:precompile
fi


# Create admin user if this is first run (optional)
# bundle exec rake admin:create


echo "Starting Discourse..."
exec "$@"

Step 4: Simplified Production Dockerfile

For a simpler setup using the official Discourse Docker image with minimal customization:

FROM discourse/discourse:3.1.3


# Set environment
ENV RAILS_ENV=production
ENV DISCOURSE_HOSTNAME=example-app.klutch.sh
ENV DISCOURSE_DEVELOPER_EMAILS=admin@example.com


# Create shared directories
RUN mkdir -p /shared/log /shared/uploads /shared/backups


# Expose port
EXPOSE 3000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:3000/srv/status || exit 1


CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000"]

This simplified version is easier to maintain and leverages the official image’s built-in configuration.

Step 5: Create Database Configuration File

Create a config/database.yml file for local testing:

production:
  adapter: postgresql
  database: <%= ENV['DISCOURSE_DB_NAME'] %>
  username: <%= ENV['DISCOURSE_DB_USERNAME'] %>
  password: <%= ENV['DISCOURSE_DB_PASSWORD'] %>
  host: <%= ENV['DISCOURSE_DB_HOST'] %>
  port: <%= ENV['DISCOURSE_DB_PORT'] || 5432 %>
  pool: <%= ENV['DISCOURSE_DB_POOL'] || 25 %>
  timeout: 5000
  prepared_statements: false
  advisory_locks: true

Step 6: Create Environment Configuration

Create a .env.example file to document required environment variables:

Terminal window
# Discourse Configuration
DISCOURSE_HOSTNAME=example-app.klutch.sh
DISCOURSE_DEVELOPER_EMAILS=admin@example.com


# Database Configuration
DISCOURSE_DB_HOST=postgres.example.com
DISCOURSE_DB_PORT=5432
DISCOURSE_DB_NAME=discourse
DISCOURSE_DB_USERNAME=discourse
DISCOURSE_DB_PASSWORD=your-secure-password


# Redis Configuration
DISCOURSE_REDIS_HOST=redis.example.com
DISCOURSE_REDIS_PORT=6379
DISCOURSE_REDIS_PASSWORD=


# SMTP Configuration (for emails)
DISCOURSE_SMTP_ADDRESS=smtp.example.com
DISCOURSE_SMTP_PORT=587
DISCOURSE_SMTP_USERNAME=noreply@example.com
DISCOURSE_SMTP_PASSWORD=smtp-password
DISCOURSE_SMTP_ENABLE_START_TLS=true


# S3 Configuration (optional, for uploads)
DISCOURSE_USE_S3=false
DISCOURSE_S3_BUCKET=
DISCOURSE_S3_REGION=
DISCOURSE_S3_ACCESS_KEY_ID=
DISCOURSE_S3_SECRET_ACCESS_KEY=


# Security
DISCOURSE_SECRET_KEY_BASE=generate-with-rake-secret

Security Note: Never commit actual passwords or sensitive data to your repository. These should be set as environment variables in the Klutch.sh dashboard.

Step 7: Create README Documentation

Create a README.md file with deployment instructions:

# Discourse on Klutch.sh


This repository contains the Docker configuration for deploying Discourse on Klutch.sh.


## Requirements


- PostgreSQL 13+ database
- Redis 6+ instance
- Persistent storage for uploads and backups
- SMTP server for email delivery


## Environment Variables


See `.env.example` for all required environment variables.


## Deployment


1. Deploy PostgreSQL and Redis instances on Klutch.sh
2. Create persistent volumes for uploads and backups
3. Set environment variables in Klutch.sh dashboard
4. Deploy this repository


## First-Time Setup


After deployment, create your admin user:


```bash
RAILS_ENV=production bundle exec rake admin:create

Updating Discourse

To update to a new version, change the version in the Dockerfile and redeploy.

### Step 8: Push to GitHub


Commit your files and push to GitHub:


```bash
git add Dockerfile docker-entrypoint.sh .env.example README.md
git commit -m "Add Discourse Docker configuration"
git remote add origin https://github.com/yourusername/discourse-klutch.git
git push -u origin main

Setting Up Database Dependencies

Discourse requires both PostgreSQL and Redis to function. You’ll need to set these up before deploying Discourse.

PostgreSQL Setup

    1. Deploy PostgreSQL on Klutch.sh

      Create a new app for PostgreSQL using the official PostgreSQL Docker image:

      FROM postgres:15-alpine
      

      ENV POSTGRES_DB=discourse
      ENV POSTGRES_USER=discourse
      # Set POSTGRES_PASSWORD via environment variables in Klutch.sh
      

      EXPOSE 5432

    2. Configure PostgreSQL Volume

      Attach a persistent volume to ensure your database persists:

      • Mount Path: /var/lib/postgresql/data
      • Size: At least 10GB (recommended 20GB+ for production)

    3. Set PostgreSQL Traffic Type

      • Traffic Type: Select TCP
      • Internal Port: 5432
      • External Port: 8000 (this is where you’ll connect from Discourse)

    4. Note Connection Details

      Your PostgreSQL connection will be available at:

      Host: your-postgres-app.klutch.sh
      Port: 8000
      Database: discourse
      Username: discourse
      Password: (set in environment variables)

Redis Setup

    1. Deploy Redis on Klutch.sh

      Create a new app for Redis:

      FROM redis:7-alpine
      

      # Optional: Enable persistence
      CMD ["redis-server", "--appendonly", "yes"]
      

      EXPOSE 6379

    2. Configure Redis Volume (optional but recommended)

      Attach a persistent volume for Redis data:

      • Mount Path: /data
      • Size: 5GB (adjust based on cache needs)

    3. Set Redis Traffic Type

      • Traffic Type: Select TCP
      • Internal Port: 6379
      • External Port: 8000 (connect from Discourse on this port)

    4. Note Connection Details

      Your Redis connection will be:

      Host: your-redis-app.klutch.sh
      Port: 8000

Deploying to Klutch.sh

Now that your dependencies are set up, deploy the Discourse application.

Deployment Steps

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Go to Create Project and give your project a meaningful name (e.g., “Discourse Forum”).

    3. Create the Discourse App

      Navigate to Create App and configure the following settings:

    4. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main)

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (Discourse serves a web application via HTTP)
      • Internal Port: Set to 3000 (the default port that Discourse listens on)

    6. Set Environment Variables

      Add the following environment variables (use the connection details from your PostgreSQL and Redis deployments):

      Database Configuration:

      • DISCOURSE_DB_HOST: Your PostgreSQL app hostname (e.g., postgres-app.klutch.sh)
      • DISCOURSE_DB_PORT: 8000 (external port for TCP traffic)
      • DISCOURSE_DB_NAME: discourse
      • DISCOURSE_DB_USERNAME: discourse
      • DISCOURSE_DB_PASSWORD: Strong password for database
      • DISCOURSE_DB_POOL: 25 (connection pool size)

      Redis Configuration:

      • DISCOURSE_REDIS_HOST: Your Redis app hostname (e.g., redis-app.klutch.sh)
      • DISCOURSE_REDIS_PORT: 8000 (external port for TCP traffic)

      Discourse Configuration:

      • DISCOURSE_HOSTNAME: Your Discourse URL (e.g., forum.example.com or example-app.klutch.sh)
      • DISCOURSE_DEVELOPER_EMAILS: Admin email addresses (comma-separated)
      • RAILS_ENV: production
      • DISCOURSE_SECRET_KEY_BASE: Generate using rake secret command (64+ character random string)

      SMTP Configuration (for emails):

      • DISCOURSE_SMTP_ADDRESS: Your SMTP server address
      • DISCOURSE_SMTP_PORT: SMTP port (usually 587 or 465)
      • DISCOURSE_SMTP_USERNAME: SMTP username
      • DISCOURSE_SMTP_PASSWORD: SMTP password
      • DISCOURSE_SMTP_ENABLE_START_TLS: true (for port 587)

      Optional S3 Configuration (for uploads):

      • DISCOURSE_USE_S3: true (if using S3 for uploads)
      • DISCOURSE_S3_BUCKET: Your S3 bucket name
      • DISCOURSE_S3_REGION: S3 region
      • DISCOURSE_S3_ACCESS_KEY_ID: AWS access key
      • DISCOURSE_S3_SECRET_ACCESS_KEY: AWS secret key

    7. Attach Persistent Volumes

      Discourse requires persistent storage for uploads, backups, and logs:

      Uploads Volume:

      • Click “Add Volume”
      • Mount Path: /shared/uploads
      • Size: 20GB+ (adjust based on expected usage)

      Backups Volume:

      • Click “Add Volume”
      • Mount Path: /shared/backups
      • Size: 10GB+ (for database backups)

      Logs Volume (optional):

      • Click “Add Volume”
      • Mount Path: /shared/log
      • Size: 5GB

    8. Configure Resource Allocation

      Discourse is resource-intensive, especially with active communities:

      • CPU: Minimum 1 CPU, recommended 2+ CPUs for active forums
      • Memory: Minimum 2GB RAM, recommended 4GB+ for production
      • Instances: Start with 1 instance (scale horizontally as traffic grows)

    9. Deploy Your Application

      Click “Create” to start the deployment. Klutch.sh will:

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image with Discourse
      • Attach the persistent volumes
      • Configure networking to databases
      • Start your Discourse container
      • Assign a URL for external access

    10. Wait for Deployment

      The initial deployment may take 5-10 minutes as Discourse:

      • Installs dependencies
      • Runs database migrations
      • Precompiles assets
      • Starts the Rails server

      Monitor the logs in the Klutch.sh dashboard to track progress.

    11. Access Your Discourse Forum

      Once deployment is complete, navigate to your assigned URL:

      https://example-app.klutch.sh

      You should see the Discourse setup wizard for first-time configuration.

Initial Configuration and Admin Setup

After your Discourse instance is running, complete the initial setup:

Creating Your Admin Account

    1. Access the Setup Wizard

      Navigate to your Discourse URL and you’ll be prompted to create an admin account.

    2. Register Your Account

      Fill in the registration form with:

      • Username
      • Email (must match one in DISCOURSE_DEVELOPER_EMAILS)
      • Password (use a strong password)

    3. Configure Basic Settings

      The wizard will guide you through:

      • Site title and description
      • Contact email
      • Category setup
      • Upload settings
      • Login methods

    4. Verify Email Configuration

      Check that email is working by sending a test email from the admin panel.

Manual Admin Creation (if needed)

If you need to create an admin account manually via command line:

Terminal window
# SSH into your container or use Klutch.sh console
cd /var/www/discourse
RAILS_ENV=production bundle exec rake admin:create


# Follow the prompts to create admin user
# Email: admin@example.com
# Password: (enter secure password)
# Repeat Password: (confirm password)

Environment Variables Reference

Complete reference of Discourse environment variables:

VariableDescriptionRequiredDefault
DISCOURSE_HOSTNAMEPublic hostname for your forumYesNone
DISCOURSE_DEVELOPER_EMAILSAdmin email addresses (comma-separated)YesNone
DISCOURSE_DB_HOSTPostgreSQL hostYesNone
DISCOURSE_DB_PORTPostgreSQL portYes5432
DISCOURSE_DB_NAMEPostgreSQL database nameYesdiscourse
DISCOURSE_DB_USERNAMEPostgreSQL usernameYesNone
DISCOURSE_DB_PASSWORDPostgreSQL passwordYesNone
DISCOURSE_DB_POOLDatabase connection pool sizeNo25
DISCOURSE_REDIS_HOSTRedis hostYesNone
DISCOURSE_REDIS_PORTRedis portNo6379
DISCOURSE_REDIS_PASSWORDRedis password (if auth enabled)NoNone
DISCOURSE_SECRET_KEY_BASESecret key for sessionsYesNone
RAILS_ENVRails environmentYesproduction
DISCOURSE_SMTP_ADDRESSSMTP server addressYesNone
DISCOURSE_SMTP_PORTSMTP portYes587
DISCOURSE_SMTP_USERNAMESMTP usernameYesNone
DISCOURSE_SMTP_PASSWORDSMTP passwordYesNone
DISCOURSE_SMTP_ENABLE_START_TLSEnable STARTTLSNotrue
DISCOURSE_USE_S3Use S3 for uploadsNofalse
DISCOURSE_S3_BUCKETS3 bucket nameIf using S3None
DISCOURSE_S3_REGIONS3 regionIf using S3None
DISCOURSE_S3_ACCESS_KEY_IDAWS access keyIf using S3None
DISCOURSE_S3_SECRET_ACCESS_KEYAWS secret keyIf using S3None
DISCOURSE_CDN_URLCDN URL for assetsNoNone
DISCOURSE_MAXMIND_LICENSE_KEYMaxMind GeoIP license keyNoNone

Production Best Practices

Security Recommendations

  • HTTPS Only: Always use HTTPS for your Discourse forum. Use Klutch.sh’s automatic TLS or configure a custom domain with SSL.
  • Strong Passwords: Use a password manager to generate strong passwords for all accounts and services.
  • Environment Variables: Store all sensitive credentials as environment variables in Klutch.sh, never in your Dockerfile or code.
  • Regular Updates: Keep Discourse updated to the latest stable version for security patches and features.
  • Database Security: Use strong passwords for PostgreSQL and restrict access to database ports.
  • Rate Limiting: Configure rate limiting in Discourse to prevent abuse and DDoS attacks.
  • Two-Factor Authentication: Enable 2FA for admin accounts in Discourse settings.
  • Backup Strategy: Implement regular backups of your database and uploads (see backup section below).
  • Security Headers: Ensure proper security headers are configured (Discourse includes good defaults).
  • Plugin Security: Only install trusted plugins from the official Discourse meta forum.

Performance Optimization

  • Database Connection Pool: Adjust DISCOURSE_DB_POOL based on your traffic (default: 25).
  • Redis Memory: Allocate sufficient memory to Redis for caching (recommended: 512MB-2GB).
  • Asset Precompilation: Precompile assets during build time to reduce startup time.
  • CDN Integration: Use a CDN for static assets by setting DISCOURSE_CDN_URL.
  • S3 for Uploads: For high-traffic sites, use S3 for uploads to reduce storage costs and improve performance.
  • Database Optimization: Regularly run VACUUM and ANALYZE on PostgreSQL.
  • Sidekiq Workers: Monitor background job queue length and add workers if needed.
  • Nginx Caching: Consider adding Nginx as a reverse proxy with caching for static assets.
  • Image Optimization: Enable Discourse’s automatic image optimization features.
  • Read Replicas: For very large forums, consider PostgreSQL read replicas.

Monitoring and Maintenance

Monitor your Discourse deployment for:

  • Application Performance: Response times, error rates, and throughput
  • Database Performance: Query times, connection pool usage, and slow queries
  • Redis Performance: Memory usage, cache hit rate, and connection counts
  • Background Jobs: Sidekiq queue length and job processing times
  • Disk Usage: Monitor uploads, backups, and log file sizes
  • Memory Usage: Track Rails and Sidekiq memory consumption
  • CPU Usage: Monitor CPU utilization under load
  • Email Delivery: Check SMTP logs for delivery failures

Backup and Disaster Recovery

    1. Database Backups

      Set up automated PostgreSQL backups:

      Terminal window
      # Manual backup
      pg_dump -h $DISCOURSE_DB_HOST -U $DISCOURSE_DB_USERNAME -d $DISCOURSE_DB_NAME > discourse-backup-$(date +%Y%m%d).sql

      Schedule regular backups using cron or a backup service.

    2. Discourse Built-in Backups

      Use Discourse’s built-in backup system:

      • Navigate to Admin → Backups
      • Click “Backup” to create a full backup
      • Backups are stored in /shared/backups
      • Download and store backups externally

    3. Volume Snapshots

      Utilize Klutch.sh volume snapshot features to backup:

      • /shared/uploads (user uploads)
      • /shared/backups (discourse backups)
      • PostgreSQL data volume

    4. Restore Process

      To restore from backup:

      Terminal window
      # Restore database
      psql -h $DISCOURSE_DB_HOST -U $DISCOURSE_DB_USERNAME -d $DISCOURSE_DB_NAME < discourse-backup.sql
      

      # Or use Discourse restore
      RAILS_ENV=production bundle exec rake backup:restore BACKUP_FILE=filename

Customization and Plugins

Installing Plugins

Discourse has a rich plugin ecosystem. To install plugins:

  1. Create a plugins directory in your repo

    Terminal window
    mkdir -p plugins

  2. Add plugin as git submodule

    Terminal window
    cd plugins
    git submodule add https://github.com/discourse/discourse-solved.git
    git submodule add https://github.com/discourse/discourse-voting.git

  3. Update Dockerfile to install plugins

    # After cloning Discourse
    COPY plugins/ /var/www/discourse/plugins/
    

    # Install plugin dependencies
    RUN cd /var/www/discourse && \
        bundle install --deployment --without test development

  4. Rebuild and deploy

Popular plugins:

Customizing Themes

Customize your forum’s appearance:

  1. Admin Panel Method (recommended):

    • Navigate to Admin → Customize → Themes
    • Click “Install” and enter theme repository URL
    • Activate the theme

  2. Custom CSS:

    • Admin → Customize → Themes → Edit CSS/HTML
    • Add custom CSS, headers, or footers

  3. Creating Custom Themes:

    • Fork an existing theme repository
    • Customize colors, fonts, and layouts
    • Install via Admin panel

Scaling Your Discourse Forum

As your community grows, you may need to scale your Discourse deployment:

Vertical Scaling

Increase resources for your existing instance:

  • Upgrade CPU: Move to 2, 4, or more CPUs
  • Increase Memory: Scale to 4GB, 8GB, or more RAM
  • Expand Storage: Increase volume sizes as needed

Horizontal Scaling

For very large communities:

  • Web Servers: Run multiple Discourse app instances behind a load balancer
  • Sidekiq Workers: Deploy dedicated Sidekiq workers for background jobs
  • Database: Use PostgreSQL read replicas for read-heavy workloads
  • Redis: Consider Redis clustering for large caches
  • CDN: Offload static assets to a CDN

Caching Strategies

  • Enable Discourse’s built-in caching features
  • Use Redis effectively for session and cache storage
  • Consider adding Varnish or Nginx caching layer
  • Implement browser caching for static assets

Troubleshooting

Cannot Access Discourse Forum

  • Check app status: Verify the app is running in Klutch.sh dashboard
  • Verify port: Ensure internal port is set to 3000
  • Traffic type: Confirm HTTP traffic type is selected
  • Review logs: Check application logs for startup errors
  • Database connectivity: Verify PostgreSQL is accessible
  • Redis connectivity: Ensure Redis is reachable

Database Connection Errors

  • Connection refused: Verify PostgreSQL is running and accessible on port 8000
  • Authentication failed: Check database credentials in environment variables
  • Database not found: Ensure database exists; create with createdb discourse
  • Network issues: Verify both apps can communicate on Klutch.sh network
  • Connection pool exhausted: Increase DISCOURSE_DB_POOL value

Redis Connection Errors

  • Cannot connect: Verify Redis is running and accessible on port 8000
  • Timeout errors: Check Redis performance and memory limits
  • Memory issues: Increase Redis memory allocation
  • Persistence problems: Verify Redis volume is correctly mounted

Email Not Sending

  • SMTP configuration: Verify all SMTP environment variables are correct
  • Authentication: Check SMTP username and password
  • Port blocked: Try different SMTP ports (587, 465, 25)
  • TLS/SSL: Ensure DISCOURSE_SMTP_ENABLE_START_TLS matches your SMTP server
  • Test email: Send test email from Admin → Email settings

Slow Performance

  • Check resources: Monitor CPU and memory usage in Klutch.sh
  • Database queries: Review slow query logs in PostgreSQL
  • Redis memory: Ensure Redis has sufficient memory allocated
  • Sidekiq backlog: Check background job queue length
  • Asset compilation: Ensure assets are precompiled
  • Scale resources: Consider upgrading CPU/memory or scaling horizontally

Upload Failures

  • Volume mounted: Verify /shared/uploads volume is correctly attached
  • Permissions: Check directory permissions in container
  • Disk space: Ensure sufficient space in uploads volume
  • S3 configuration: If using S3, verify credentials and bucket access
  • File size limits: Check Discourse and Nginx file size limits

Migration Errors

  • Database version: Ensure PostgreSQL version compatibility (13+)
  • Pending migrations: Run bundle exec rake db:migrate manually
  • Failed migrations: Check logs for specific migration errors
  • Rollback: If needed, rollback with bundle exec rake db:rollback

Asset Compilation Fails

  • Memory issues: Increase container memory for asset compilation
  • Node.js version: Ensure compatible Node.js version in image
  • Yarn lockfile: Verify yarn.lock is present and valid
  • Precompile at build: Move asset compilation to Dockerfile
  • Clear cache: Try bundle exec rake assets:clobber and recompile

Upgrading Discourse

To upgrade Discourse to a new version:

Minor Version Updates

  1. Update Dockerfile version:

    # Change from v3.1.3 to v3.1.4
    git checkout v3.1.4

  2. Test locally (optional but recommended):

    Terminal window
    docker build -t discourse-test .
    docker run -it discourse-test

  3. Commit and push:

    Terminal window
    git add Dockerfile
    git commit -m "Upgrade Discourse to v3.1.4"
    git push

  4. Klutch.sh will automatically rebuild and deploy

Major Version Updates

For major version updates (e.g., v3.0 to v3.1):

  1. Review release notes: Check Discourse releases for breaking changes
  2. Backup everything: Create full database and uploads backup
  3. Test in staging: If possible, test upgrade in a staging environment
  4. Update Dockerfile: Change version in Dockerfile
  5. Review migrations: Check for any required manual migrations
  6. Deploy: Push changes and monitor deployment carefully
  7. Verify: Test critical functionality after upgrade

Rollback Procedure

If an upgrade fails:

  1. Revert Dockerfile: Change back to previous version
  2. Push changes: Klutch.sh will rebuild with old version
  3. Restore database: If database migrations occurred, restore from backup
  4. Investigate: Review logs to understand what went wrong

Advanced Configuration

Custom Domain Setup

To use a custom domain for your Discourse forum:

  1. Add domain in Klutch.sh: Navigate to your app settings and add custom domain
  2. Configure DNS: Point your domain to the provided Klutch.sh address
  3. Update environment variable: Set DISCOURSE_HOSTNAME to your custom domain
  4. Verify SSL: Klutch.sh automatically provisions SSL certificates
  5. Redeploy: Restart your app to pick up new hostname

SSO Integration

Discourse supports Single Sign-On for seamless authentication:

  1. Configure SSO provider: Set up your SSO provider (OAuth2, SAML, etc.)
  2. Install plugin: Install appropriate SSO plugin for your provider
  3. Set environment variables: 
    DISCOURSE_SSO_URL=https://sso.example.com
    DISCOURSE_SSO_SECRET=your-sso-secret
  4. Enable in admin: Configure SSO settings in Discourse admin panel

CDN Configuration

For improved performance with a CDN:

  1. Set up CDN: Configure your CDN to point to your Discourse instance
  2. Add environment variable: 
    DISCOURSE_CDN_URL=https://cdn.example.com
  3. Configure CORS: Ensure CORS headers allow CDN domain
  4. Update asset URLs: Discourse will automatically use CDN for assets

Custom Email Templates

Customize email templates sent by Discourse:

  1. Access admin panel: Navigate to Admin → Customize → Email Templates
  2. Select template: Choose template to customize (welcome email, digest, etc.)
  3. Edit content: Modify subject and body with custom text and styling
  4. Use variables: Leverage Discourse template variables for personalization
  5. Preview: Test emails before making changes live

Additional Resources

Conclusion

Deploying Discourse on Klutch.sh with Docker provides a robust, scalable platform for building online communities. By following this comprehensive guide, you’ve set up a production-ready Discourse instance with proper database configuration, persistent storage, security measures, and performance optimizations. Your community platform is now ready to foster engaging discussions and grow your online community. Remember to keep Discourse updated, monitor performance, maintain regular backups, and customize your forum to meet your community’s unique needs.