Self-hosting Discourse in production (2026): hardware, app.yml, runbook

community.example.com / sidekiq

Sidekiq dashboard

Workers / Queues / Retries

Processed

128,402

Failed

14

Busy

5/5

Enqueued

8,194

[default] Jobs::CleanUpUploads · 0.4s

[low] Jobs::EmitWebHookEvent · 1.2s

[critical] Jobs::ProcessPost · queued for 47 minutes — worker pool saturated

[default] Jobs::PostAlert · 0.2s

[low] Jobs::PullHotlinkedImages · timeout

SimpleReview

.sc-log-row.error
containers/app.yml:18

Sidekiq queue keeps backing up — bump UNICORN_SIDEKIQS to 4 and rebuild?

Fix it →

Fix #214 ready · 1 file changed
+1 −1 in containers/app.yml

SimpleReview reads a stuck Sidekiq queue, drafts the app.yml tweak, prepares a site fix — production runbook in motion.

Hardware sizing — measured, not guessed

Every "Discourse system requirements" post on the internet recites the same 2 GB RAM minimum. That's true but useless. Here's what we actually measured on each VPS tier with a synthetic load of 200 concurrent users browsing latest, plus image-baking and Sidekiq jobs running in the background.

ARM works. Hetzner's CAX line and Oracle Free Tier ARM both run Discourse fine — image_optim binaries are compiled for arm64 in the official image, Sidekiq/Postgres/Redis don't care. Bench it before committing because Ruby/Rails performance per ARM vCPU is ~85-90% of x86_64 in our tests, but cost per request is better.

The app.yml mental model

Most newcomers see discourse/discourse on Docker Hub and try docker run -d -p 80:80 discourse/discourse. Don't. That image is the build base, not the application.

Discourse uses an unusual deploy pattern: discourse_docker (a separate repo) contains a Bash launcher that:

1. Reads containers/app.yml — your declarative config (env vars, hooks, plugins, hostname)
2. Pulls the discourse/base image
3. Runs ./launcher bootstrap — boots the base, runs the hooks (which install plugins, configure Postgres, set the hostname, build assets), then commits the resulting state as a new image
4. Runs ./launcher start — runs that committed image as the live container

The result: every site has a custom-built image. Plugins and config live in the image, not as runtime mounts. This is why adding a plugin requires ./launcher rebuild app — you're literally building a new image with the new plugin baked in.

Trade-off: rebuilds are slower than docker compose updates (5-15 min depending on plugins), but the production runtime is dead simple — one container, no orchestration, no service mesh, no init system. The whole stack lives inside one Docker container — Postgres, Redis, Sidekiq, Rails, image_optim binaries.

# containers/app.yml — minimal production excerpt
templates:
  - "templates/postgres.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"
  - "templates/web.ratelimited.template.yml"

expose:
  - "80:80"
  - "443:443"

params:
  db_default_text_search_config: "pg_catalog.english"
  db_shared_buffers: "256MB"

env:
  LANG: en_US.UTF-8
  UNICORN_WORKERS: 4
  UNICORN_SIDEKIQS: 2
  DISCOURSE_HOSTNAME: 'community.example.com'
  DISCOURSE_DEVELOPER_EMAILS: '[email protected]'
  DISCOURSE_SMTP_ADDRESS: 'smtp.mailgun.org'
  DISCOURSE_SMTP_PORT: 587
  DISCOURSE_SMTP_USER_NAME: '[email protected]'
  DISCOURSE_SMTP_PASSWORD: ''
  LETSENCRYPT_ACCOUNT_EMAIL: '[email protected]'

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

run:
  - exec: echo "Beginning of custom commands"

Once you understand this, the rest of Discourse ops becomes obvious: plugins go in hooks: after_code, mail credentials are env vars, hostname changes mean a rebuild. The full reference for these directives lives in the discourse_docker repo's samples/ directory.

Self-host vs Discourse cloud — the honest comparison

Discourse, Inc. sells managed hosting starting at $100/mo (Standard) and scaling by user count. Their pitch: zero ops, automatic upgrades, premium support, an SLA. Real comparison:

Decision rule we'd actually use: below ~1k DAU and a dev team comfortable with Linux ops, self-host wins on price and control. Above ~10k DAU or for a non-technical owner, the time cost of self-hosting crosses Discourse's pricing and cloud is the rational choice. Between those two — depends on whether you want custom plugins (self-host) or you want to never page yourself at 3 a.m. (cloud).

The 15-point production runbook

What's intentionally out of scope

Things this guide doesn't cover and where to find them:

• Initial install — official 30-Minute Install on meta.discourse.org is excellent and current. We won't re-write it.
• Theme development — well covered by Discourse's theme-creator docs and the theme-creator.discourse.org sandbox.
• Onebox / oneboxing custom URLs — niche; check OneboxEngine source in the main repo.
• Multi-site hosting — Discourse, Inc.'s actual platform. Possible but not maintained outside their team; if you need it, hire them or rebuild from scratch.

Frequently asked