Discourse installs one supported way: the official Docker-based installer on a 64-bit Linux server you can SSH into, with at least 1GB of RAM plus swap, 10GB of disk, and a mail provider ready before you start. The installer takes about ten minutes. The parts that take longer are the ones the quick start treats as prerequisites: sizing the server honestly, getting transactional email to work, and knowing how upgrades, backups and app.yml behave once the forum is live. This is the full path.
The top results are the project’s own install guide and the community’s self-hosting thread, which are correct and terse. They assume you have a server, a domain and an SMTP account, and they stop at the first page load. Every failed Discourse install I have seen failed on something outside that scope: too little memory, an email provider that silently dropped the activation mail, or a rebuild that ran out of disk. This post covers the guide and the outside.
Table of contents
- What Discourse needs, honestly
- Step one: the server and Docker
- Step two: the installer and the questions it asks
- Step three: the email step that breaks most installs
- Living with it: app.yml, upgrades, backups
- What it costs, and where to run it
- How this fits the rest of the stack
- FAQ
What Discourse needs, honestly
The project only supports Docker installs, and it says why: Discourse is a Rails application with Postgres, Redis, Sidekiq and Nginx around it, and the container packages all of that into one thing you can rebuild. It also means Discourse is not a fit for a platform that runs a single web process from a repository; it wants a server with Docker and root.
The stated minimums are a modern single-core CPU with two recommended, 1GB of RAM with swap, 10GB of disk, and a 64-bit Linux that runs Docker. Those are minimums for a small community, and two of them are worth exceeding on day one.
Memory. 1GB works with swap for a forum with a few hundred users. The rebuild step, which compiles assets, is the peak, and on 1GB it leans on swap heavily and takes a long time. 2GB is comfortable; 4GB is what a busy forum with plugins wants.
Disk. 10GB is the install. Uploads, the Postgres data, the Docker images from each rebuild and the backups all grow on the same disk, and a forum that has been running for a year with image uploads can be tens of gigabytes. Start with 40GB or put uploads in object storage.
The 16GB VPS post has the method for sizing memory from a workload; for Discourse the answer for most communities is a 2 vCPU, 4GB server.
You also need, before starting: a domain with an A record pointed at the server, an SMTP provider with credentials, and ports 80 and 443 free on the box.
Step one: the server and Docker
Provision the server, log in as root over SSH, and update it. The installer will install Docker and git if they are missing, but doing it yourself first means you see the errors.
ssh root@your-server-ip
apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
docker --versionAdd swap if the server has under 4GB; the installer will offer to but it is better to do it deliberately:
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile && swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstabCheck nothing is listening on 80 or 443. A fresh server has nothing; a server that already had a web server does, and the installer’s own Nginx will fail to bind.
lsof -i :80 -i :443
# if nginx or apache2 shows up:
systemctl stop nginx && systemctl disable nginxFinally confirm the domain resolves to this server before running the installer, because the certificate step will fail if it does not: dig +short forum.example.com should print the server’s IP.
Step two: the installer and the questions it asks
The official one-line installer clones the Docker configuration into /var/discourse and runs a setup wizard.
wget -qO- https://raw.githubusercontent.com/discourse/discourse_docker/main/install-discourse | sudo bashIf you would rather see each step, the manual equivalent is:
git clone https://github.com/discourse/discourse_docker.git /var/discourse
cd /var/discourse
chmod 700 containers
./discourse-setupThe wizard asks for six things. The hostname, which must be the domain you pointed at the server. The admin email, which becomes the first admin account. The SMTP server, port, username and password for outgoing mail. Optionally a Let’s Encrypt email for the certificate, which you want. It then writes containers/app.yml and runs the first bootstrap, which pulls the base image, installs Discourse, compiles assets and starts the container.
Bootstrap takes five to fifteen minutes depending on the server. On a 1GB box with swap it can take longer and look hung; it is not. When it finishes, the forum answers on the domain over HTTPS and shows a page asking you to register the admin account.
The account is activated by email, which is why the SMTP step comes before the first page load and why it is the step that fails most often.
Step three: the email step that breaks most installs
Discourse cannot work without outgoing mail: the admin activation, every signup, every notification and every digest is an email. The installer does not verify the SMTP details; it writes them to app.yml and moves on, so a typo or a provider that needs a verified sending domain shows up only as an activation email that never arrives.
Three rules save the most time. Use a transactional email provider, not a personal mailbox; consumer SMTP has sending limits and reputation problems that make forum mail vanish. Verify the sending domain with the provider before installing, with the SPF and DKIM records they ask for, because unverified senders are dropped or spam-foldered. Use the port and encryption the provider documents, usually 587 with STARTTLS.
If the activation mail does not arrive, check in this order:
cd /var/discourse
./launcher logs app | grep -i -E "smtp|mail|550|535"
./launcher enter app
rails c
# inside the console:
Discourse::Application.config.action_mailer.smtp_settingsThen fix the values in containers/app.yml under DISCOURSE_SMTP_* and rebuild. Rebuilding is the only way settings in app.yml take effect, and it restarts the forum for a few minutes.
Living with it: app.yml, upgrades, backups
Everything about the install lives in /var/discourse/containers/app.yml: the hostname, the email settings, the memory tuning, the plugin list and the volumes. Two commands run everything.
cd /var/discourse
./launcher rebuild app # apply app.yml changes, pull a new base image, or recover
./launcher logs app # Docker logs for the container
./launcher enter app # a shell inside the containerUpgrades come two ways. Minor versions upgrade from the admin panel at /admin/upgrade with a button, without a rebuild. Major versions, base image updates and plugin additions need ./launcher rebuild app, which is a few minutes of downtime and the moment a disk that is nearly full causes trouble, because the rebuild pulls a new image beside the old one. Keep 5GB free and run ./launcher cleanup occasionally.
Backups are configured in the admin panel and land in /var/discourse/shared/standalone/backups, which is on the same disk as everything else. Point them at object storage in the settings, or copy them off the server on a schedule, because a backup on the disk that fails is not a backup. Restoring is a button in the same panel, and it is worth doing once on a test server so the first real restore is not the first ever.
Uploads are on the disk too by default. A forum with images should move them to S3-compatible storage early, before the migration is large.
The whole thing is the docker compose up —build pattern with a project-specific launcher wrapped around it, and the operational habits are the same: the config file is the source of truth, and a rebuild applies it.
What it costs, and where to run it
Discourse is a stateful, multi-process application that wants a whole server with Docker and root, which makes it a VPS workload rather than a push-a-repo one. A 2 vCPU, 4GB server with 40GB of disk is the realistic starting point for a community that will grow; the vps price post covers what drives that number. Add the transactional email provider’s plan and object storage for uploads and backups, and a small forum costs a modest monthly figure plus the hours to run it.
The hours are the real line. Upgrades, the occasional rebuild that needs attention, disk watching, and the OS patches underneath are yours. That is fine for a community with a technical owner. For a community without one, the project’s own hosting or a partner is the honest alternative.
RunxBuild does not host Discourse; a Docker web service on the platform runs one process from one image and Discourse wants a full server. Where the platform does fit around a forum is the rest of the project: the marketing site in front of it as a static site, a managed Postgres for an application that integrates with the forum’s API, and a Node or Python service that handles webhooks from it. The Docker applications docs cover what that single-process service shape looks like.
How this fits the rest of the stack
Install Discourse the supported way: a Docker-capable server with 2GB or more of memory and 40GB of disk, a domain already pointing at it, and a verified transactional email provider before you run the installer. Keep app.yml as the source of truth, rebuild to apply changes, move backups and uploads off the server’s disk early, and budget the hours as well as the server. For a sense of what the rest of the project around the forum costs, the RunxBuild hosting calculator shows a static site, a service and a managed database as separate line items beside the VPS you rent for the forum itself.
Useful related references:
- docker compose up —build: When You Need It and Why It Sometimes Changes Nothing
- 16GB VPS: How to Tell Whether You Actually Need One
- VPS Price: What Drives It, and the Line Items That Are Not On It
- Docker Applications on RunxBuild
- Managed Databases on RunxBuild
FAQ
What are the minimum requirements to install Discourse?
A 64-bit Linux server that runs Docker, with SSH root access, 1GB of RAM plus swap, 10GB of disk and a modern CPU, per the official guide. In practice 2GB of memory and 40GB of disk is the sensible starting point, because the rebuild step is memory-hungry and uploads, backups and Docker images all grow on the same disk.
Can I install Discourse without Docker?
Not in any supported way. The project only supports its Docker-based installer and explicitly does not support cPanel, Plesk or manual installs. The container bundles Rails, Postgres, Redis, Sidekiq and Nginx with tested configuration, and the launcher script handles upgrades and rebuilds against it.
Why is my Discourse activation email not arriving?
Almost always the SMTP settings. Use a transactional email provider rather than a personal mailbox, verify the sending domain with SPF and DKIM before installing, and use the port and encryption the provider documents. Check the container logs for SMTP errors, correct the DISCOURSE_SMTP values in app.yml, and rebuild.
How do I upgrade Discourse?
Minor versions upgrade from the admin panel at /admin/upgrade. Major versions, base image updates and plugin changes need a rebuild from /var/discourse with the launcher rebuild command, which takes a few minutes of downtime. Keep several gigabytes of disk free first, because the rebuild pulls a new image alongside the old one.
Where should Discourse backups go?
Not on the same disk as the forum. Backups default to a folder under /var/discourse/shared, so configure the admin backup settings to upload to S3-compatible object storage, or copy them off the server on a schedule. Test a restore once on a scratch server so the first real restore is not the first ever.