Run a Discourse forum without losing weekends to it.
Six practical guides written by self-hosters, for self-hosters. Working configs, real benchmarks, copy-paste code. Pick what's broken right now and fix it tonight.
community.example.com / latest
SimpleReview reads the broken plugin call, drafts the modifyClass fix, prepares a site fix — straight to your repo.
Why this site exists
Most Discourse content online is either the official 30-minute install (great, current) or a SaaS sales pitch dressed up as a tutorial (not great). This handbook fills the gap in between — what happens after install, what breaks in production, what to do when the docs stop.
Real configs, not theory
Every walkthrough is a working
app.yml, a working Mailgun route, a working Flask provider. Tested on a real Discourse instance before publishing.Decision-ready numbers
Hardware sizing measured on $5/$12/$24/$48 VPS tiers. Cost comparison with Discourse cloud. Decision rules you can act on, not generic "minimum 2 GB" boilerplate.
Free and lock-in-free
No paywall, no newsletter capture, no SaaS retargeting. Discourse is GPL-2.0; this handbook respects the same spirit. We monetize via SimpleReview, an opt-in tool.
Honest about what this is
We're not Civilized Discourse Construction Inc. — we're a small team that has been self-hosting Discourse for clients and our own communities since 2018. This handbook is what we wished existed when we hit each wall: rebuild OOMs on 2 GB VPSes, plugins that silently broke after Ember 5, IMAP that quietly stopped polling. Nothing here is theoretical. Every benchmark and config was run on real production. If we got something wrong, tell us on GitHub and we'll fix it.
The six guides
Each guide solves one production problem with copy-paste configs and validated repros. None of them are install guides — those belong in official Discourse docs. Pick what you're stuck on right now.
Production reference
Self-hosting Discourse in production (2026)
Hardware sizing on four VPS tiers (measured), the
app.yml mental model, an honest cost comparison with Discourse cloud, and a 15-point production runbook you can paste into your ops doc.
Plugin development
Build your first Discourse plugin (2026)
plugin.rb, api.modifyClass for Ember 5, hot reload, server endpoints, plugin tests. Real code that builds against current Discourse main.
API integration
Discourse API cookbook — 10 working recipes
Auth differences (Api-Key vs User-Api-Key), rate limits, create topic, send DM, upload image, search, pagination. Copy-paste curl + Python.
Mail setup
Reply by email — Mailgun, IMAP, POP3
Pick a mode and get it working. MX/SPF/DKIM prerequisites, a working Mailgun route, and a log-line debug map for ten failure modes.
SSO / auth
DiscourseConnect SSO provider
HMAC-SHA256 signing in Flask + Express. Sequence diagram, common "bad signature" fixes, sync flags, Discourse-as-IdP variant.
Migration
Migrate phpBB → Discourse
Import script walkthrough — env vars, attachments, username fixup, post-import Sidekiq drain. vBulletin notes included.
What you'll dodge by reading this
A short list of mistakes we paid for the first time so you don't have to.
Rebuild OOMs on 2 GB VPSes (rebuild needs 1.5 GB free ON TOP of running Discourse)
Running
docker run discourse/discourse and wondering why nothing works (it's a build base, not the app)Ember 5 plugin breakage from older guides that still teach
Discourse.X.reopenSilent IMAP polling failures after a Gmail or M365 password change
"Bad signature" loops in DiscourseConnect when your provider HMAC is in the wrong order
Missing attachments after a phpBB import because the importer can't see the source
files/ directorySidekiq backlog of 50k jobs after a large import, with no plan to drain it
API rate-limit cascades because your client doesn't honour
Retry-AfterLost reply-by-email because
%{reply_key} wasn't literal in your address pattern"User has no email" on first SSO login because of a typo in the payload field name
Stuck on Discourse right now?
Two paths: read the guide that matches your pain, or install SimpleReview and let it draft the fix on whatever element you click.
Frequently asked
Who wrote this handbook?
The Vibers team — a small group that has been self-hosting Discourse for clients and our own communities since 2018. We're not affiliated with Civilized Discourse Construction Inc. This is what we wished existed when we hit each wall.
Is it free?
Yes — every guide and benchmark on this site is free. We monetize through SimpleReview (a Chrome extension that drafts code fixes for any site, Discourse forums included), not through paywalled documentation.
Does it cover the official 30-minute install?
No, on purpose. The official Discourse install guide is excellent and current — we don't try to replace it. We pick up where it ends: production sizing, real plugin development, API integration, mail troubleshooting, SSO, migration.
Why should I trust your benchmarks?
Hardware sizing was measured in 2026 on Hetzner CX-line VPSes with synthetic load via
k6. Each plugin / API / SSO walkthrough is built and run on a real Discourse instance before publishing. If you spot something wrong, file a GitHub issue and we'll fix it.