Discourse Installation Notes

Discourse is a new generation discussion forum. I found that Discourse is very suitable for personal note taking. One notable feature of Discourse is that the users can focus on conversations. Besides, it supports Markdown as the message markup language. This is the reason why I like it very much.

In the rest of the post, I would like to write down how did I install Discourse on a Digital Ocean droplet.


To install Discourse, there are five essential steps:

  1. Setup the Mail Server.
  2. Create a Droplet.
  3. Setup the Swap File: If the VPS plan does not have sufficient RAM (less than 1G), it is required to setup a swap file.
  4. Installation: Install Docker, install Discourse and launch the containers.
  5. Configure Discourse.

Setup the Mail Server

It is required to have a mail server for Discourse. If you already have one, then just use it. If you don't have a mail server, then you can register one for free at SparkPost, which allows you to send 10k e-mails per month.

  1. Visit SparkPost and click the TRY FOR FREE button on the top right corner.

  2. Sign up for SparkPost.

    1. Fill in the e-mail and the password.
    2. Solve the CAPTCHA.
    3. Agree to the terms of use.
    4. Click the Sign Up button.
  3. Verify your account by clicking the links in the confirmation e-mail.

    Note: If you didn't receive the confirmation e-mail, you can request a new e-mail by clicking "ACCOUNT -> SENDING DOMAINS" and click the link in the top bar.

  4. Before we can send e-mails with SparkPost, we have to claim that we are the owner of a domain name. This will require us to configure the DNS records.

    2. Click the NEW DOMAIN button.
    3. Fill in the domain name and click ADD DOMAIN.
    4. Update DNS records for SPF and DKIM. Click the Configure link for more details. In summary, you have to add two different TXT records.
    5. After updating the DNS TXT records, click the Test links for verification.
  5. Create a new API key.

    1. Click "ACCOUNT -> API & SMTP".
    2. Click the "NEW API KEY" button.
    3. Fill in the API Key Name, e.g. "discourse".
    4. Select the Send via SMTP in the API Permissions section.
    5. Fill in the SparkPost password again.
    6. Copy the API key.

Create a Droplet

After logging into Digital Ocean, click on the Create Droplet button on the top right corner. In the new page, you have to fill in the following fields:

  1. Droplet Hostname -- Choose a good name for your installation.
  2. Select Size -- All plans are fine. I tried the cheapest $5/mo plan, and it works perfectly.
  3. Select Region -- Choose a region for the data center. I chose New York data center. Pick one which is close to your visitors.
  4. Select Image -- The default image, Ubuntu 14.04 x64, is suggested. It is recommended by the Discourse development team.
  5. Add your SSH public key to the Add SSH Keys section.

Now, we can click on the Create Droplet button and wait for a while. After the droplet is created, then try to log in with ssh command.

Note: You can check the SSH server fingerprint by clicking the Console Access button in the Digital Ocean admin console.

Setup the Swap File

Discourse requires 1GB RAM to run without problems. If you are running with 500MB RAM, then you must enable the swap file. Otherwise, you will not be able to build the Discourse container.

Here are the instructions to setup the swap file:

# Create a new swap file.
$ sudo fallocate -l 4G /swapfile

# Change the file permission.
$ sudo chmod 600 /swapfile

# Format the swap file.
$ sudo mkswap /swapfile

# Enable the swap file.
$ sudo swapon /swapfile

# Check that the swap file has been enabled.
$ sudo swapon -s
Filenam    Type  Size     Used  Priority
/swapfile  file  4194300  0     -1

# Add the swap file to fstab
$ sudo bash -c "echo '/swapfile none swap sw 0 0' >> /etc/fstab"

# Reboot the machine now.
$ sudo reboot

You can further tweak the configuration by reading: How to Add Swap on Ubuntu 14.04.


In this section, we would like to install Discourse. There are three steps:

  1. Harden Droplet - Make your Droplet much more secure.
  2. Install Docker - Install Docker for Discourse.
  3. Install Discourse - Install Discourse and modify the settings.

Harden Droplet

Before installing Discourse, it will be better to harden the Droplet. We should:

  1. Enable automatic upgrade
  2. Disable the root account

First, we can enable automatic upgrade with:

$ sudo dpkg-reconfigure -plow unattended-upgrades
# Choose <yes> to enable automatic upgrade.

Second, we would like to disable the root accoount. However, before doing so, we have to create a new user account:

# Create a new user.
$ sudo adduser [username]
Enter new UNIX password:
Retype new UNIX password:

# Grant sudo access to that user.
$ sudo visudo
# ... Add "[username] ALL=(ALL:ALL) ALL"

# Copy SSH keys.
$ sudo mkdir -p /home/[username]/.ssh
$ sudo cp /root/.ssh/authorized_keys /home/[username]/.ssh
$ sudo chown -R [username]:[username] /home/[username]/.ssh

# Logout.
$ exit

Log in with the new account and disable the root account with:

# Lock the root password.
$ sudo passwd -l root

# Disable the ssh root login.
$ sudo vi /etc/ssh/sshd_config
# ... Change "PermitRootLogin" to "no"

# Restart ssh server.
$ sudo service ssh restart

Install Docker

It is preferred to install Discourse through the prebuilt Docker image. Thus, we have to install Docker beforehand.

To install Docker, run the following command:

$ wget -qO- https://get.docker.com/ | sudo sh

Install Discourse

Now, we can install Discourse with:

# Switch to root user.
$ sudo -s

# Create a directory for Discourse.
> mkdir /var/discourse

# Clone the Discourse docker image.
> git clone https://github.com/discourse/discourse_docker.git \

# Change the directory to /var/discourse.
> cd /var/discourse

# Copy the sample configuration.
> cp samples/standalone.yml containers/app.yml

# Edit the configuration.
> vi containers/app.yml

It is mandatory to change the following fields:

  • DISCOURSE_DEVELOPER_EMAILS - This is the e-mail that will be treat as the administrator of the Discourse installation.
  • DISCOURSE_HOSTNAME - This is the domain name for your Discourse installation.
  • Mail Server Configurations - These are the settings for the mail server. Here we are using the SparkPost as the example.
    • DISCOURSE_SMTP_ADDRESSES, e.g. smtp.sparkpostmail.com
    • DISCOURSE_SMTP_PORT, e.g. 587
    • DISCOURSE_SMTP_PASSWORD - The API key that you have created (40-digit hexadecimals.)

And then, we can bootstrap the installation with:

./launcher bootstrap app

This will take some time. Get a cup of coffee and wait for a while. :-)

After the bootstrap succeed, we can launch the Discourse installation with:

./launcher start app

Congratulations! You should be able to checkout the installation through your favorite browser!

Note: If you have SSL certificates, then don't register or input anything now.

Install SSL Certificate

If you have an SSL certificate, then it's time to install the SSL certificate now!

To install SSL certificate:

  1. Create directory:

    mkdir -p /var/discourse/shared/standalone/ssl
  2. Copy the private key to /var/discourse/shared/standalone/ssl/ssl.key and the certificate to /var/discourse/shared/standalone/ssl/ssl.crt.

  3. Edit the configuration:

    1. Append "templates/web.ssl.template.yml" to templates section.
    2. Add "443:443" to the expose section.

Now, we should rebuild the container with:

# Rebuild the container.
./launcher rebuild app

Configure Discourse

As the last step of installation, we have to create an administrator account so that we can fill in several important settings and moderate the forum.

Create an Admin Account

  1. Open the browser and visit your Discourse installation.

  2. Click the Sign Up button on the top right corner.

  3. Fill in the E-mail, Username, Name, and Password.

    Note: To be an adminstrator, the e-mail must be identical to DISCOURSE_DEVELOPER_EMAILS specified in app.yml.

  4. Click the link in the verification e-mail.

Update Settings

  1. Visit http[s]://[domain-name]/admin and click Settings.
  2. Fill in the fields.
  3. If you have installed SSL certificate, check the "Security -> use https" field.
  4. If you want this Discourse installation work as a private installation, then you can check the following check boxes:
    1. Login -> invite only
    2. Login -> login required
    3. Login -> must approve users

Install Discourse Tagging Plug-in

If you wish to install Discourse Tagging Plug-in, here are the instructions:

  1. Open app.yml.

  2. Append following line to hooks -> after_code -> exec -> cmd:

    git clone https://github.com/discourse/discourse-tagging.git
  3. Rebuild the container with ./launcher rebuild app

  4. Open the admin console in the browser, and enable the plug-in at Plugins -> Plugins -> Settings -> tagging enabled.


These are my notes to get a Discourse installation. We have covered:

  1. Register a SparkPost account and create an API key.
  2. Create a droplet and enable the swap file.
  3. Install Discourse and fill in the necessary settings.

Hope you enjoy this. You can find more information in the Discourse GitHub repository.