Discourse Administration & Management

1. Fundamentals: Identity & Trust Architecture

Trust levels answer “how much can this account do?” Groups answer “which capabilities and spaces does this person need?” Staff still own policy, sanctions, and hard moderation calls.

Trust Level System (TL0 - TL4)

An automated promotion system based on engagement metrics (reading time, topics viewed, replies) that grants escalating privileges. Default TL0: at most 2 hyperlinks and 1 image per post. Default TL3: at least 50% of days visited in the rolling 100-day window plus reply, reading, like, and moderation-history criteria; reading requirements are capped at 500 topics and 20,000 posts. TL3 can be earned and lost. TL4 is different: it is manual promotion by staff. Use a custom group when someone needs one capability without a wholesale trust-level promotion.

Group-Based Permissions

Security architecture assigning read/write/reply access to custom groups rather than purely relying on Trust Levels. Create a @beta-testers group. In Category → Edit → Security, remove everyone, then grant beta-testers See/Reply/Create to make the category private to that group. Avoid assigning specific users individual permissions. Always assign users to a Group, and apply permissions to the Group.

Anonymization vs. Deletion

Anonymization removes account identity while preserving contributions; deletion removes the account and may require separate handling of authored posts. Use Anonymize User on the user’s admin page when policy calls for removing account identity while preserving contributions; Discourse replaces the username and removes fields such as email, name, date of birth, avatar, profile, API keys, and third-party auth links. Anonymization is not a universal legal answer: authored posts, revisions, staff logs, and backups can still matter. Authenticate requests and follow a jurisdiction-specific retention and erasure policy.

Tags vs. Categories (Information Architecture)

Categories provide access boundaries and major partitions; tags provide flexible, overlapping organization across topics. Instead of making Support > MacOS > Version 15 (deep categories), make a Support category and mandate a Tag Group containing #macos and #v15. Writing #macos in a post links to the tag; it does not apply the tag to the topic. Avoid many empty categories because they create ambiguous posting choices—not because of an invented database threshold.

2. Production Operations & Recovery

Use the loop backup → change → observe → verify → retain rollback. Commands below assume the supported discourse_docker layout at /var/discourse.

Standalone vs. Multiple Containers

The standalone template minimizes operational complexity; separate data.yml and web_only.yml containers enable independent web builds, redundancy, and horizontal scaling. Stay standalone while one host meets capacity and recovery objectives. Split when measured CPU, database I/O, queue latency, storage, rebuild duration, or availability requirements justify operating PostgreSQL, Redis, web nodes, load balancing, and shared uploads separately. There is no universal “1 million pageviews” cutover. Multi-container operation is more flexible but also more complex; rehearse migration and rollback from a current backup.

Logs & Incident Triage

Logster, Rails logs, container output, and proxy/database logs reveal different failure layers. For an HTTP 500, check /logs, then ./launcher logs app, then /var/discourse/shared/standalone/log/rails/production.log. Capture rebuild output with tee while the rebuild runs. Logs can contain email addresses, IPs, request data, and secrets. Redact before sharing and restrict access and retention.

Backups That Can Restore

A backup is useful only when its upload scope, off-host copy, version compatibility, plugins, and restore procedure are known. Create a backup including uploads, download it off-host, build a sandbox on the same Discourse version, enable allow restore, restore, then verify login, posts, uploads, themes, and required plugins. Backups contain users, settings, themes, and credential-equivalent material. Encrypt and access-control them. Plugin code itself comes from container configuration and must also be restored.

Signed Webhooks & Scoped API Keys

Webhooks push selected events to an HTTPS endpoint; separate API keys authorize calls back into Discourse. Create a webhook at /admin/api/web_hooks/new, choose only required events, set a secret, verify X-Discourse-Event-Signature as HMAC-SHA256 over the raw body, and use Ping. Give each integration its own minimal key. Return quickly, queue work, and deduplicate retries. Never trust account/email payloads before signature verification or reuse one unrestricted admin key across services.

Rate Limits & Reverse Proxies

Discourse applies global per-IP and API-key-class throttles; clients must treat HTTP 429 as backpressure. Defaults verified Aug 2026: 200 requests/IP/minute and 50/IP/10 seconds; user API 20/minute and 2,880/day; admin API 60/minute shared across admin keys. A proxy that forwards the wrong client IP can make every visitor appear to come from one address. Fix forwarding before raising limits; back off with jitter and retry only safe operations.

3. UI Customization & Development

The Customization Hierarchy (Use Top to Bottom)

Discourse Theme CLI

A command-line tool allowing developers to build themes locally in VS Code and hot-reload them to a live server via API.

Copy

gem install discourse_theme
discourse_theme new my-custom-component
discourse_theme watch my-custom-component

Live sync targets a real site. Use staging or a non-default development theme, a minimally scoped key, and never commit .discourse_theme credentials.

Plugin Outlets

Designated hooks in the Discourse HTML/Handlebars templates where custom UI elements can be injected safely. Use the core developer toolbox to reveal available outlets, then target a current outlet such as discovery-list-container-top with a uniquely named connector. Wrapper outlets can replace core content and accept only one active connector. Inspect the outlet arguments and smoke-test after platform updates.

4. AI, Automation, Workflows & Reporting

Automate classification and routing before sanctions. Keep execution logs, narrow the scope, measure false positives, and preserve human review for irreversible actions.

Discourse AI: Triage & Classification

AI triage uses an Agent through Discourse Automation to classify posts and conditionally tag, move, reply, or hide. Limit the rule to first topics in Support; instruct the Agent to return only REVIEW for likely credential exposure; set “Search for Text” to REVIEW and apply a moderator-review tag. It requires Discourse AI plus Discourse Automation, incurs model cost, and can be wrong. Start with routing/tagging, sample outcomes, and bound input/output tokens.

AI Search & Related Topics

Semantic similarity can surface conceptually related topics that do not share the same literal words. Test a known paraphrase set—“factory reset,” “wipe configuration,” and “restore defaults”—and compare semantic results with standard search before changing user-facing defaults. Embedding the historical corpus is background work and provider-dependent. Monitor queues, cost, privacy terms, and result quality; do not promise a specific duplicate-reduction rate.

Discourse Automation

Automation runs one supported script for a compatible trigger, schedule, or API call. Use a user_added_to_group trigger with a supported welcome-message script rather than writing a custom plugin for one notification. Scripts support specific triggers; Automation is not a universal multi-step canvas. Verify the current script/trigger matrix in your instance.

Discourse Workflows

Workflows is the new node-based builder for multi-step triggers, conditions, actions, external calls, delays, and flow control. On a new topic: check category → branch on required fields → call a ticket API → store the returned ID → reply with the case number; inspect executions before enabling broadly. Availability as of Aug 2026: the official listing describes it as bundled with core and available on hosted Business/Enterprise plans; the July 2026 preview calls it experimental. Confirm current plan and version.

Data Explorer (Read-Only SQL)

Data Explorer runs saved, read-only PostgreSQL queries against the live Discourse database for custom reporting.

Find top readers who have not posted in 30 days; time_read is seconds:

Copy

SELECT u.username,
       us.days_visited,
       ROUND(us.time_read / 3600.0, 1) AS hours_read
FROM users u
JOIN user_stats us ON us.user_id = u.id
WHERE u.last_posted_at < CURRENT_DATE - INTERVAL '30 days'
ORDER BY us.time_read DESC
LIMIT 20;

Data Explorer is read-only and enforces a query timeout, but expensive scans still waste resources. Filter early, limit output, and run heavy reporting off-peak.

5. Community Strategy & Common Mistakes

Forums earn repeat use when discussion produces durable, searchable knowledge and belonging. Choose friction, curation, and automation according to the community’s actual abuse and support patterns.

Synthesis as a Service (Curation)

Curation turns long-lived discussions into an accessible answer, decision record, or maintained reference. When a 100-post incident thread reaches a conclusion, draft a summary, have a domain owner verify it, and add the final remediation and date to the original post. An AI summary can omit dissent or invent consensus. Keep links to the decisive posts and name the human reviewer.

The Ecosystem Bridge (Chat vs. Forum)

Chat supports fast coordination; Discourse preserves decisions and knowledge that must remain searchable. Use chat for the live incident room, then publish a Discourse postmortem containing timeline, root cause, remediation owner, and follow-up dates. Do not copy private chat into a public topic without participant and data-classification review.

Risk-Adjusted Onboarding

Authentication and review friction should match the cost of abuse and the audience’s tolerance. A private customer forum can use DiscourseConnect tied to active product accounts; an open hobby forum may keep native signup, TL0 limits, watched words, and staff review. SSO creates a new critical dependency and recovery path. Do not require identity providers that exclude legitimate members without a documented reason.

Common Anti-Patterns (What NOT to Do)

6. Pre-Launch / Audit Checklist

Progress is saved locally to your browser.