How to install Discourse with the official Docker installer

Discourse is an open-source discussion platform used for community forums, product support boards and internal knowledge sharing. The project supports one install method for production: a Docker container managed by the discourse_docker launcher, which also handles Let's Encrypt certificates and upgrades. This guide prepares a Ubuntu or Debian server, runs the official installer and setup wizard, hardens the new forum, and shows how to back it up, restore it and keep it updated.

Step 1 — Install Docker from Docker's repository

The Discourse installer installs Docker with Docker's convenience script if Docker is missing. Docker recommends that script only for testing, so install Docker Engine from the official repository first; the installer then skips that step. Follow Install Docker on Ubuntu or Install Docker on Debian, then check:

docker --version
sudo systemctl is-active docker

Step 2 — Add swap on small servers

On a server with 2 GB of RAM or less, add swap before the first build, as the Discourse troubleshooting notes advise:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

free -h should now show 2 GB of swap.

Step 3 — Open the firewall and check DNS

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
dig +short forum.example.com

The dig output must be your server's public IP address (install dnsutils if dig is missing). If you use your own domain, wait until this is true before you continue, because the wizard checks it and Let's Encrypt needs it.

Step 4 — Download, read and run the official installer

The installer is a short bootstrap script in the discourse_docker repository. It must run as root. It installs git if it is missing, installs Docker only if it is missing, clones discourse_docker into /var/discourse (if that folder is already a git checkout, it resets it to the latest version and discards local changes there) and then starts the discourse-setup wizard. Download it and read it before you run it:

wget -qO install-discourse https://raw.githubusercontent.com/discourse/discourse_docker/main/install-discourse
less install-discourse
sudo bash install-discourse

The official guide shows the same thing as a one-line wget … | sudo bash; downloading first only lets you see what will run.

The wizard asks for:

1. Admin email address(es). Accounts registered with these addresses become administrators.
2. Your own domain or a free subdomain. Answer with your host name, for example forum.example.com, or claim a discourse.diy subdomain with the six-digit code shown in your Discourse ID account (valid for 10 minutes).
3. SMTP. Enter your provider's host, for example smtp.example.com, port 587, user name and password, or skip it to use Discourse ID logins.

After you confirm, the installer builds and starts the container, which takes about 5 to 10 minutes. Let's Encrypt certificates are requested and renewed automatically.

Check the result:

cd /var/discourse
sudo ./launcher logs app | tail -n 20
curl -I https://forum.example.com

curl should return an HTTP 200 or a redirect, with no certificate error.

Step 5 — Create the admin account and finish setup

Open https://forum.example.com and click Sign Up. Register with one of the admin email addresses from the wizard (or sign in with Discourse ID if you skipped SMTP); with SMTP you receive a confirmation email first. Discourse then opens its own setup wizard for the forum name, look and access settings.

Recommended first settings in Admin → Settings:

• Require two-factor authentication for staff with the enforce_second_factor setting.
• Decide who may join: invite_only for private communities, or must_approve_users to review sign-ups.
• Set login_required if the forum should not be publicly readable.

Step 6 — Keep the host secure

The Discourse guide recommends automatic security updates for the host and fail2ban against SSH brute-force attempts:

sudo apt install unattended-upgrades fail2ban
sudo dpkg-reconfigure -plow unattended-upgrades
sudo systemctl status fail2ban --no-pager

All forum settings, including SMTP credentials, live in /var/discourse/containers/app.yml, which only root can read. After editing it, apply the change with a rebuild:

cd /var/discourse
sudo nano containers/app.yml
sudo ./launcher rebuild app

A rebuild takes the forum offline for a few minutes.

Back up and restore

Discourse makes its own backups. In Admin → Backups you can start one by hand; scheduled backups are controlled in Admin → Settings → Backups:

Local backups are stored in /var/discourse/shared/standalone/backups/default, which only root can read. Copy them to a folder your admin user owns:

sudo mkdir -p /opt/backups/discourse
sudo rsync -a /var/discourse/shared/standalone/backups/default/ /opt/backups/discourse/
sudo chown -R $USER:$USER /opt/backups/discourse

Then pull them to another machine regularly, for example from your own computer:

rsync -av admin@203.0.113.10:/opt/backups/discourse/ ./discourse-backups/

Also keep a copy of /var/discourse/containers/app.yml. For off-site storage you can set backup_location to S3 and fill in the s3_backup_bucket and access key settings.

To restore onto a fresh install, upload the archive without renaming it (Discourse reads metadata from the file name) and run the restore inside the container:

sudo mkdir -p /var/discourse/shared/standalone/backups/default
sudo cp forum-2026-10-09-033000-v20261001000000.tar.gz /var/discourse/shared/standalone/backups/default/
cd /var/discourse
sudo ./launcher enter app
discourse enable_restore
discourse restore forum-2026-10-09-033000-v20261001000000.tar.gz
exit

Running discourse restore without a file name lists the backups it can see. A restore turns off outgoing email for non-staff users; turn it back on with the disable_emails setting. Allow three to five times the backup size in free disk space.

Update Discourse

Discourse emails the admins when a new version is available. Take a backup first, then update either in the browser at https://forum.example.com/admin/upgrade or from the command line:

cd /var/discourse
sudo ./launcher rebuild app

On the main branch the launcher first updates its own checkout ("Ensuring launcher is up to date"), then rebuilds the container on the current base image. A rebuild causes a few minutes of downtime. Keep the host itself updated with sudo apt update && sudo apt upgrade.

Troubleshooting

The wizard says port 80 or 443 is already in use

Another web server is running. Find it with sudo lsof -i :80 and sudo lsof -i :443, then stop and disable it, for example sudo systemctl disable --now nginx or apache2, and run the installer again.

The domain check fails

The A record does not point to this server yet, or it has not propagated. Check with dig +short forum.example.com. The wizard accepts --skip-connection-test to continue anyway, but Let's Encrypt still needs correct DNS, so fix the record first where possible.

The build or bootstrap fails

Read the container output with sudo ./launcher logs app, open a shell with sudo ./launcher enter app, and look at /var/discourse/shared/standalone/log/rails/production.log. Running out of memory is the most common cause on small servers; add swap (Step 2) and rebuild.

Confirmation emails do not arrive

Check the SMTP host, port (587) and credentials in containers/app.yml, then rebuild. Make sure your sending domain has the SPF and DKIM records your email provider asks for. The admin panel's email logs under Admin → Email show delivery attempts.

Next steps

• Add real-time chat for your team with Matrix Synapse and Element.
• Compare with a federated microblogging server in Install Mastodon.
• Read the official Discourse install guide and the guides on meta.discourse.org.
• See servers for communities on the social network hosting page.