# How to install Discourse with the official Docker installer

> Install a Discourse community forum on Ubuntu or Debian with the official installer, automatic HTTPS, safe login settings, scheduled backups and updates.

Difficulty: Intermediate\
Tested on: Ubuntu 24.04 LTS, Ubuntu 26.04 LTS, Debian 12, Debian 13

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.

## Prerequisites

- A server running Ubuntu 24.04 or 26.04 LTS (Discourse recommends Ubuntu LTS) or Debian 12 or 13, 64-bit.
- A non-root user with `sudo` rights and SSH key login: see [Secure a new Linux server](/guides/secure-a-new-linux-server) and [Set up SSH keys](/guides/ssh-keys).
- A host name such as `forum.example.com` with a DNS A record pointing to the server, or a Discourse ID account if you want a free `discourse.diy` subdomain.
- Ports 80 and 443 free: no other web server may run on this machine.
- Optional: an SMTP provider for digests and reply-by-email.

Requirements from the Discourse install guide:

| Resource | Minimum (official) | Suggested starting point |
|---|---|---|
| CPU | 1 core | 2 or more cores (official recommendation) |
| RAM | 1 GB with swap | 2 GB or more (official recommendation) |
| Disk | 10 GB | 20 GB or more (official recommendation), plus space for backups and uploads |
| OS | 64-bit Linux | Ubuntu LTS |

The installer tunes the number of web workers and the database memory to the RAM and CPU it detects.

## 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](/guides/install-docker-ubuntu) or [Install Docker on Debian](/guides/install-docker-debian), then check:

```bash
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:

```bash
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

```bash
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:

```bash
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.

> **Note**
>
> Outbound port 25 is closed by default on HyperDC VPS. For services bought for a term of 3 months or longer, it is opened on request: [open a support ticket](/guides/support-tickets). Until then, send mail through an SMTP relay on port 587.

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:

```bash
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:

```bash
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:

```bash
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**:

| Setting | Default | Meaning |
|---|---|---|
| `backup_frequency` | 7 | Days between automatic backups (0 turns them off) |
| `backup_time_of_day` | 3:30 | Start time in UTC |
| `maximum_backups` | 5 | Number of backups kept |
| `backup_with_uploads` | on | Include uploaded files, not only the database |

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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](/guides/install-matrix-synapse).
- Compare with a federated microblogging server in [Install Mastodon](/guides/install-mastodon).
- Read the official [Discourse install guide](https://github.com/discourse/discourse/blob/main/docs/INSTALL-cloud.md) and the guides on meta.discourse.org.
- See servers for communities on the [social network hosting](/social-network-hosting) page.

## Frequently asked questions

### Do I still need an SMTP provider for Discourse?

Not to get started. If you skip SMTP in the setup wizard, users sign in with Discourse ID (email and social logins). Activity digests, mailing-list mode and replying by email still need SMTP, which you can add later under Admin, Email or by re-running the wizard.

### How much memory does Discourse need?

The official minimum is 1 GB of RAM with swap, 1 CPU core and 10 GB of disk on 64-bit Linux. Discourse recommends 2 GB or more RAM, 2 or more cores and 20 GB or more disk on an Ubuntu LTS release.

### Can I run other websites on the same server?

By default the Discourse container takes ports 80 and 443. Discourse's community guide shows how to switch the container to a Unix socket and put Nginx with Certbot on the host in front of it, but you then manage certificates on the host yourself. A separate server for Discourse is simpler.

### Where are Discourse backups stored?

Local backups are written to /var/discourse/shared/standalone/backups/default. By default Discourse makes one every 7 days, keeps 5 and includes uploads. You can send them to S3-compatible storage instead and should copy them off the server in any case.

### Can I use a free subdomain instead of my own domain?

Yes. The installer can claim a free discourse.diy subdomain through your Discourse ID account and creates the DNS record for you. With your own domain you create the A record yourself before installing.

---

Source: <https://hyperdc.com/guides/tutorials/install-discourse>\
Updated: 2026-10-09