Discourse Forum Installation

Discourse is a modern, open-source forum platform built on Ruby on Rails that provides an engaging space for community discussion and knowledge sharing. With built-in moderation tools, user reputation systems, and mobile optimization, Discourse powers thousands of communities worldwide. This guide covers Docker-based installation, email configuration, SSL setup, admin panel configuration, and plugin installation.

Table of Contents

Prerequisites

Ensure you have:

  • Ubuntu 20.04 LTS or later
  • Root or sudo access
  • A registered domain name
  • Minimum 4GB RAM (8GB+ recommended)
  • 40GB available disk space
  • Basic Linux administration knowledge
  • Docker and Docker Compose installed

Update system packages:

sudo apt update && sudo apt upgrade -y

System Requirements

Verify system meets requirements:

Check OS version:

cat /etc/os-release
uname -m

Verify available resources:

free -h
df -h

Docker Installation

Install Docker:

sudo apt install -y docker.io docker-compose

Start and enable Docker:

sudo systemctl start docker
sudo systemctl enable docker

Add current user to docker group:

sudo usermod -aG docker $USER
newgrp docker

Verify Docker installation:

docker --version
docker-compose --version

Discourse Docker Setup

Clone Discourse Docker repository:

sudo mkdir -p /var/discourse
cd /var/discourse
sudo git clone https://github.com/discourse/discourse_docker.git .

Build Discourse Docker containers:

sudo chmod 700 containers
cd containers
sudo cp samples/standalone.yml ./app.yml

Edit Docker configuration:

sudo nano /var/discourse/containers/app.yml

Configure essential settings:

## If you want to run Discourse in a subfolder, you will need to do the following:
# 1) Change the prefix `discourse` to e.g. `my-forum` everywhere in this file
# 2) Change "discourse" to "my-forum" in the cli launcher
# 3) Rename container from `discourse` to `my-forum`
DISCOURSE_HOSTNAME: 'forum.example.com'

DISCOURSE_DEVELOPER_EMAILS: '[email protected]'

## IMPORTANT: The database password should not contain '#' or '$' or characters that confuse bash.
DISCOURSE_DB_PASSWORD: "SecurePassword123!"

## If you update the domain, you must recreate the container to get a new certificate
LETSENCRYPT_ACCOUNT_EMAIL: '[email protected]'

## These templates are for various site styles:
DISCOURSE_SMTP_ADDRESS: "smtp.gmail.com"
DISCOURSE_SMTP_PORT: 587
DISCOURSE_SMTP_USER_NAME: "[email protected]"
DISCOURSE_SMTP_PASSWORD: "your-app-password"
DISCOURSE_SMTP_ENABLE_START_TLS: "true"

DISCOURSE_NOTIFICATION_EMAIL: '[email protected]'

## The CDN address for this Discourse instance (configured to pull)
# DISCOURSE_CDN_URL: https://discourse-cdn.example.com

DISCOURSE_MAXMIND_DB_DOWNLOAD_URL: 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=YOUR_LICENSE_KEY&suffix=tar.gz'

Build and start Discourse:

cd /var/discourse
sudo ./launcher bootstrap app

The bootstrap process takes 5-10 minutes. Monitor progress:

sudo docker logs discourse -f

Start the Discourse container:

sudo ./launcher start app

Verify container is running:

sudo docker ps | grep discourse

Email Configuration

Configure SMTP for email notifications:

Edit Docker configuration:

sudo nano /var/discourse/containers/app.yml

Update SMTP settings:

DISCOURSE_SMTP_ADDRESS: "smtp.your-provider.com"
DISCOURSE_SMTP_PORT: 587
DISCOURSE_SMTP_USER_NAME: "[email protected]"
DISCOURSE_SMTP_PASSWORD: "your-app-password"
DISCOURSE_SMTP_ENABLE_START_TLS: "true"
DISCOURSE_NOTIFICATION_EMAIL: '[email protected]'

Rebuild the container:

sudo ./launcher rebuild app

Wait for rebuild to complete:

sudo docker logs discourse -f

Test email configuration in admin panel:

  1. Navigate to Admin → Email
  2. Send test email
  3. Verify delivery

SSL Certificate Setup

Discourse Docker automatically configures Let's Encrypt SSL.

Verify SSL is configured in app.yml:

grep -i letsencrypt /var/discourse/containers/app.yml

Should show:

LETSENCRYPT_ACCOUNT_EMAIL: '[email protected]'

Access Discourse web interface:

Navigate to https://forum.example.com

The SSL certificate is automatically generated during first access.

Monitor certificate generation:

sudo docker logs discourse -f

Verify certificate is valid:

sudo openssl s_client -connect forum.example.com:443 -showcerts

Admin Panel Configuration

Complete initial setup:

  1. Navigate to https://forum.example.com
  2. Create admin account during onboarding
  3. Configure site settings

Access admin panel:

  1. Login with admin account
  2. Click menu → Admin

Configure site settings:

  1. Admin → Settings → General
    • Site title
    • Site description
    • Default locale
    • Default trust level

Configure categories:

  1. Admin → Categories
  2. Create forum categories (General, Announcements, etc.)
  3. Set permissions for each category

Configure user trust levels:

  1. Admin → Settings → Users
  2. Set requirements for different trust levels
  3. Configure auto-trust-level promotion

User Management

Invite users to forum:

  1. Admin → Users
  2. Click "Invite Users"
  3. Enter email addresses
  4. Set invitations expire time

Manage user accounts:

  1. Admin → Users
  2. Search for user
  3. Edit permissions, trust level, or groups

Configure SSO (optional):

  1. Admin → Settings → Login
  2. Enable OAuth or custom SSO
  3. Configure provider details

Create user groups:

  1. Admin → Groups
  2. Click "New Group"
  3. Add members
  4. Set group permissions

Plugin Installation

Explore available plugins:

Navigate to https://discourse.org/plugins to find available plugins.

Install plugin via admin panel:

  1. Admin → Plugins
  2. Click "Install Plugin"
  3. Enter GitHub repository URL
  4. Wait for installation to complete

Popular plugins to install:

  • discourse-solved: Mark topics as solved
  • discourse-calendar: Calendar events
  • discourse-reactions: Emoji reactions
  • discourse-encrypt: Post encryption

Install via Docker configuration:

sudo nano /var/discourse/containers/app.yml

Add to plugins section:

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone https://github.com/discourse/discourse-solved.git
          - git clone https://github.com/discourse/discourse-calendar.git

Rebuild container:

sudo ./launcher rebuild app

Backup and Maintenance

Configure automated backups:

  1. Admin → Backups
  2. Set backup frequency
  3. Configure backup storage

Create manual backup:

  1. Admin → Backups
  2. Click "Backup"
  3. Wait for process to complete

Backup location on server:

ls -lh /var/discourse/shared/standalone/backups/

Create backup script:

sudo nano /usr/local/bin/discourse-backup.sh

Add:

#!/bin/bash

DISCOURSE_DIR="/var/discourse"
BACKUP_DIR="/backups/discourse"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Create backup
cd $DISCOURSE_DIR
docker exec discourse rake backup:create

# Copy backup
cp /var/discourse/shared/standalone/backups/*.tar.gz "$BACKUP_DIR/discourse-backup-$DATE.tar.gz"

# Keep only 30 days
find $BACKUP_DIR -type f -mtime +30 -delete

echo "Backup completed: $DATE"

Make executable:

sudo chmod +x /usr/local/bin/discourse-backup.sh

Schedule daily backups:

sudo crontab -e

Add:

0 2 * * * /usr/local/bin/discourse-backup.sh >> /var/log/discourse-backup.log 2>&1

Update Discourse:

cd /var/discourse
sudo ./launcher stop app
sudo git pull origin main
sudo ./launcher rebuild app

Troubleshooting

Check Docker container status:

sudo docker ps | grep discourse

View container logs:

sudo docker logs discourse -f
sudo docker logs discourse | tail -100

Access Discourse console:

sudo docker exec -it discourse bash
cd /var/www/discourse
rails console

Restart container:

sudo ./launcher stop app
sudo ./launcher start app

Check disk usage:

df -h
du -sh /var/discourse

Conclusion

Discourse forum is now fully deployed with Docker, providing a modern, feature-rich community platform. With email notifications, SSL encryption, and comprehensive admin tools, you have a complete discussion platform. Regular backups, plugin installation, and community moderation features enable a thriving forum. Configure categories, trust levels, and plugins to customize the experience for your community members.