Self-Host Discourse on a VPS

Reddit's API changes broke a decade of third-party clients. Facebook Groups buries every post under an algorithm. Slack's free tier amnesia kicks in at 90 days. If you're trying to build a community that actually belongs to you — searchable, moderatable, ownable — Discourse is the gold standard. Stack Overflow communities, Apple developer forums, Boing Boing, BBC, Atlassian — all running on Discourse.

This guide installs Discourse via the official Docker-based installer (the only supported path), configures SMTP for outbound email (without which Discourse can't function — even signup verification requires email), sets up HTTPS, walks through SSO and OAuth login providers, and covers the operational pieces — backups, plugin installation, performance tuning — that you'll actually need within the first month.

1. Why SMTP comes first

Discourse is email-centric in a way that surprises most people. Signup verification, password reset, watched-topic notifications, daily digest, weekly summary, moderator alerts, PM delivery — all email. If outbound mail doesn't work, Discourse doesn't work. Not "works poorly" — actually broken. Users can't even confirm their accounts.

Set up your SMTP provider before you start the installer. Discourse asks for SMTP credentials during install and refuses to proceed without them. Options:

Provider	Free tier	Notes
Mailgun	5,000 emails/mo for first 3 months	Best for new forums; clean Discourse integration
Postmark	100 emails/mo free, $15/mo for 10k	Best deliverability, premium pricing
Amazon SES	62,000/mo from EC2	Cheapest at scale, requires AWS account
SendGrid	100 emails/day free	Reliable but free tier tiny
Your own Postfix	—	Don't. See our mail server guide for why outbound from your own VPS gets dropped to spam.

Sign up, verify your sending domain (SPF + DKIM + DMARC DNS records — the provider walks you through it), and have these credentials ready before step 3:

• SMTP host (e.g. smtp.mailgun.org)
• SMTP port (usually 587)
• SMTP username
• SMTP password / API key

2. Prepare the VPS

apt update && apt upgrade -y
apt install -y git curl ca-certificates ufw

# Discourse needs swap if you have less than 2 GB RAM
# Skip this on a Pro plan (4 GB+) — but harmless to add anyway
if [ ! -f /swapfile ] && [ $(free -m | awk '/^Mem:/{print $2}') -lt 4000 ]; then
  fallocate -l 2G /swapfile
  chmod 600 /swapfile
  mkswap /swapfile
  swapon /swapfile
  echo '/swapfile none swap sw 0 0' >> /etc/fstab
fi

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

3. Run the Discourse installer

Discourse ships its own opinionated installer. Don't try to docker-compose it manually — you'll fight the installer for years.

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

./discourse-setup

The interactive installer asks:

• Hostname for your Discourse: community.example.com
• Email address for admin account: yours
• SMTP server address: from your SMTP provider (step 1)
• SMTP port: usually 587
• SMTP username + password
• Notification email: noreply@example.com
• Optional Maxmind account: skip unless you want IP geolocation
• Let's Encrypt account email: yours (used for cert renewals)

The installer writes config to /var/discourse/containers/app.yml, builds the Docker image (takes 5–10 minutes), starts the container, and runs first-time database setup. Total elapsed: 12–18 minutes on a Pro plan.

When it finishes, visit https://community.example.com. You'll get the Discourse welcome screen prompting you to sign up.

4. First boot and admin signup

The first account to register at the hostname you specified becomes the admin automatically. Use the same email you gave the installer — that's the account that gets admin privileges.

Discourse emails you a verification link. Click it. You're now logged in as the admin.

On first login Discourse launches its setup wizard — community name, theme color, logo, basic info. Walk through it. None of these choices are permanent; everything is editable later under Admin → Customize.

5. HTTPS setup

The installer already handled this. Discourse uses an embedded Nginx + Let's Encrypt setup inside its container. Certificate renewal is automatic.

If you want to put Discourse behind your own reverse proxy (sharing the VPS with other apps), set expose in app.yml to "127.0.0.1:8080" instead of public ports, then proxy from your external Nginx. This is documented in detail at meta.discourse.org — generally avoid unless you really need to.

6. Essential first-day config

Things to do on day one to avoid pain on day 30:

Set up your About page: Admin → Customize → About. The default has placeholder text. Replace it; this page is the second-most-visited page on every forum.

Configure trust levels: Admin → Settings → search "trust". Discourse's secret sauce is its progressive permissions model — new users (TL0) can't post links or images, regular users (TL2) can flag, leaders (TL3) can edit other posts. Default thresholds work, but review them so you know what's happening.

Disable signup for the first week: Settings → "signup" → toggle login required. Lets you set up categories, post some seed content, invite a small initial cohort. Open signups once the place looks active.

Create categories: Categories tab → + New Category. Aim for 5–8 categories at launch. More than that fragments a small community; fewer can't represent breadth.

7. Installing plugins

Plugins are added by editing app.yml — NOT through the web UI. This catches people off-guard. The pattern:

cd /var/discourse
nano containers/app.yml

Find the hooks: section. Inside the after_code: hook, the git clone entries are your plugin list:

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

After editing, rebuild:

./launcher rebuild app

Rebuild takes 5–10 minutes and incurs ~3 minutes of downtime. Plan plugin changes during low-traffic hours.

Plugins worth installing on day one: discourse-solved (mark a reply as "the solution" — great for Q&A communities), discourse-calendar (event scheduling), discourse-chat-integration (forward category posts to Slack/Discord webhooks).

8. SSO and OAuth login

Most forums don't need their own password infrastructure. Discourse supports OAuth out of the box for Google, Facebook, Twitter, GitHub, Discord, plus SAML and DiscourseConnect (their custom SSO protocol).

Enabling Google login (representative example):

1. Visit Google Cloud Console → APIs & Services → Credentials → Create OAuth 2.0 Client ID
2. Application type: Web application. Authorized redirect URI: https://community.example.com/auth/google_oauth2/callback
3. Copy the Client ID and Client Secret
4. In Discourse: Admin → Settings → search "google" → paste credentials, enable google_oauth2 enabled

GitHub, Discord, and Facebook follow the same pattern. SAML for enterprise SSO (Okta, Azure AD, OneLogin) needs the official discourse-saml plugin, installed as in step 7.

9. Backups and upgrades

Discourse has built-in backups. Admin → Backups → enable automatic daily backups. Backups go to /var/discourse/shared/standalone/backups/ on the VPS — a starting point but not a safe one. If the VPS dies, your backups die with it.

Configure remote backup destination: same Backups page → settings → S3 backup bucket + access keys. Backups auto-upload after each run. Use any S3-compatible service: AWS S3, Backblaze B2, Wasabi, MinIO.

Upgrading Discourse: a banner appears in the admin panel when updates are available. Most updates can be installed by clicking the banner — applies migrations, restarts the app, 30-second downtime. Larger updates (Discourse calls them "rebuild required") need a CLI rebuild:

cd /var/discourse
git pull
./launcher rebuild app

Always back up before a rebuild. Bring a USB-key full of beverages to the upgrades that need it. Most don't.

10. Reference: scaling, performance, gotchas

Resource needs by community size

Active community size	Recommended plan	RAM	Notes
Up to 100 active users	Starter ($7.99)	2 GB	Tight — every restart eats RAM. Swap helps.
100–1,000 active	Pro ($15.99)	4 GB	Sweet spot for most communities
1,000–10,000 active	Premium ($35.99)	8 GB	Multiple Sidekiq workers, faster searches
10,000+ active	Dedicated server	16+ GB	Separate Postgres + Redis VPS, multi-app stack

Performance tuning

Edit app.yml to expose Discourse's tunables. Useful environment variables:

env:
  DISCOURSE_DB_SHARED_BUFFERS: 256MB     # Postgres shared buffer
  DISCOURSE_RUBY_GC_HEAP_INIT_SLOTS: 600000   # Ruby GC heap
  UNICORN_WORKERS: 4                      # web workers — 2 per CPU core is fine
  UNICORN_SIDEKIQS: 2                     # background job workers

Defaults assume a 1 CPU / 1 GB VPS. On a 4-core / 4 GB Pro plan, bump UNICORN_WORKERS to 6 and SIDEKIQS to 3 — significantly snappier UI.

Discourse vs phpBB / vBulletin / NodeBB

Discourse is the most modern, mobile-first, JavaScript-heavy. phpBB and vBulletin are PHP page-reload-per-action forums from a different era — fine if you want the classic feel and don't care about real-time updates. NodeBB is in the same era as Discourse, slightly lighter on RAM, smaller ecosystem.

Migrate from phpBB / vBulletin via Discourse's official importers (Ruby scripts that read the old DB and write Discourse posts). Most migrations under 4 hours of run time for forums up to 100k posts.

Common pitfalls

• Gmail SMTP doesn't work — Discourse needs sustained delivery, Gmail throttles it. Use Mailgun/Postmark/SES.
• Mailing-list-mode doesn't work without inbound email — for users to reply by email, you need to point an email subdomain at Discourse and configure POP3/IMAP. Optional but powerful.
• Plugins added without rebuild don't load — every plugin change requires ./launcher rebuild app.
• Free tier of SMTP runs out fast — 5,000 emails sounds like a lot until your first 1,000-user notification goes out. Plan to pay for SMTP at any scale.

FAQ

Related posts

Tutorial

Set Up a Mail Server (Postfix + Dovecot)

Why you DON'T want to run your own outbound SMTP for Discourse — and what your alternatives look like.

Tutorial

Install & Secure PostgreSQL

Discourse uses Postgres internally — useful background for performance tuning.

Pillar

The Complete Self-Hosting Guide

Where forums fit in a broader self-hosted community stack.