Guides - Deploy Discourse through the Linode Marketplace

Discourse is a self-hosted open-source discussion platform that provides a forum, mailing list, chat room, and more.

Before You Begin

Discourse requires that you have a domain name and access to a personal SMTP email server before installation. This requires either having access to a pre-existing SMTP server, or setting up an SMTP Relay through a third party. The Discourse Marketplace App requires an SMTP username and password for a server under your control in order to successfully complete the installation.

• If you don’t already have your domain hosted at Linode, the install creates A and AAAA domain records for you.

  • This means you need a Linode API token. If you don’t have a token, you must create one before continuing.

  • Ensure that your domain registrar is using Linode’s name servers.

• Additionally, the SMTP user must be able to send email from noreply@your-domain.com for administrator account verification.

  • For example, if you enter a subdomain of discourse and your domain name is example.com, then the SMTP user must be able to send email from noreply@discourse.example.com.

  • You are not required to use a subdomain. Therefore, if you only setup example.com with no subdomain, the email used for verification would be noreply@example.com.

Deploying a Marketplace App

The Linode Marketplace allows you to easily deploy software on a Compute Instance using the Cloud Manager. See Get Started with Marketplace Apps for complete steps.

1. Log in to the Cloud Manager and select the Marketplace link from the left navigation menu. This displays the Linode Create page with the Marketplace tab pre-selected.

2. Under the Select App section, select the app you would like to deploy.

3. Complete the form by following the steps and advice within the Creating a Compute Instance guide. Depending on the Marketplace App you selected, there may be additional configuration options available. See the Configuration Options section below for compatible distributions, recommended plans, and any additional configuration options available for this Marketplace App.

4. Click the Create Linode button. Once the Compute Instance has been provisioned and has fully powered on, wait for the software installation to complete. If the instance is powered off or restarted before this time, the software installation will likely fail.

To verify that the app has been fully installed, see Get Started with Marketplace Apps > Verify Installation. Once installed, follow the instructions within the Getting Started After Deployment section to access the application and start using it.

Configuration Options

• Supported distributions: Ubuntu 20.04 LTS
• Recommended minimum plan: 4GB Shared Compute Instance

Discourse Options

• Email for Admin Account and Let’s Encrypt certificate: The email you wish to use for the administrator account and the SSL certificate. This email address receives notifications when the certificate needs to be renewed.
• SMTP Address: The address for SMTP. Discourse uses this for sending email.
• SMTP Username: The username for the SMTP account entered above. The SMTP user must be able to send email from noreply@your-fully-qualified-domain.com for account verification.
• Password for SMTP User: The password for the SMTP account listed above.

Custom Domain

Discourse requires that you have a domain name and SMTP email. These fields are required for a successful installation and are marked Required. Additionally, the SMTP user must be able to send email from noreply@your-fully-qualified-domain.com for account verification.

• Linode API Token: If you wish to use the Linode’s DNS Manager to manage DNS records for your custom domain, create a Linode API Personal Access Token on your account with Read/Write access to Domains. If this is provided along with the subdomain and domain fields (outlined below), the installation attempts to create DNS records via the Linode API. See Get an API Access Token. If you do not provide this field, you need to manually configure your DNS records through your DNS provider and point them to the IP address of the new instance.
• Subdomain: The subdomain you wish to use, such as www for www.example.com.
• Domain: The domain name you wish to use, such as example.com.

Limited User (Optional)

You can optionally fill out the following fields to automatically create a limited user for your new Compute Instance. This is recommended for most deployments as an additional security measure. This account will be assigned to the sudo group, which provides elevated permission when running commands with the sudo prefix.

• Limited sudo user: Enter your preferred username for the limited user.
• Password for the limited user: Enter a strong password for the new user.
• SSH public key for the limited user: If you wish to login as the limited user through public key authentication (without entering a password), enter your public key here. See Creating an SSH Key Pair and Configuring Public Key Authentication on a Server for instructions on generating a key pair.
• Disable root access over SSH: To block the root user from logging in over SSH, select Yes (recommended). You can still switch to the root user once logged in and you can also log in as root through Lish.

Getting Started After Deployment

Discourse is now installed and ready to use.

1. Your A and AAAA Domain records for the domain and subdomain, if you designated one, have been created and you should see them in the Cloud Manager.

   • In the Cloud Manager DNS Manager, confirm that there are now an entries for your domain and possible subdomain.
   • Configure rDNS on your Linode to point to subdomain.your-domain.com or your-domain.com if you did not enter a subdomain.

2. While the installation has created the A and AAAA domain records, it does not create the email records you need. In the Cloud Manager DNS Manager, add the MX, TXT, and any other records required to send email as specified by your email provider.

3. You can now navigate to the Discourse app in your browser with the fully qualified domain name you entered during configuration, https://subdomain.your-domain.com or https://your-domain.com.

4. Discourse welcomes you with a “Congratulations” screen and a Register button. Click the Register button to create the administrator account.

5. On the Register Admin Account page, select one of the email addresses you entered during installation and enter a Username and Password. Then click the Register button.

6. Discourse sends a confirmation email for account verification from your SMTP server. After you receive the email and confirm, you are redirected to the welcome screen where you are walked through a wizard to setup your Discourse.

7. Once you are finished the setup wizard, Discourse launches the main discussion listing page where you can start adding discussion topics.

Software Included

The Discourse Marketplace App installs the following software on your Linode:

Troubleshooting Email

If you did not get a confirmation email during setup it could be caused by several issues.

Check DNS Records

Ensure that you have correctly setup the email DNS records required to send email as specified from your email provider. The Installer does not do this for you as every email host has different required records and values.

Change the Confirmation Email Sender

Discourse sends this email from noreply@subdomain.your-domain.com. The SMTP user you entered during setup must have permissions to send from this address. If this is not the case, and you did not receive the email, you can change this address in a configuration file.

1. Connect to your Marketplace App’s Linode via SSH.

2. Change into the directory /var/discourse/containers/:

   cd /var/discourse/containers
   

3. Edit the file app.yml with the text editor of your choice. Uncomment the following line and edit the email address to the email you wish to send the confirmation email from. The SMTP user must have permissions to send email from this address.

   File: /var/discourse/containers/app.yml

   1 2 3 4 5 6 7

   ... ## If you want to set the 'From' email address for your first registration, uncomment and change: - exec: rails r "SiteSetting.notification_email='noreply@example.com'" ## After getting the first signup email, re-comment the line. It only needs to run once. ...

4. Save the file and exit.

5. Change directory into /var/discourse and rebuild Discourse.

   cd ..
   ./launcher rebuild app
   

6. Once Discourse has finished rebuilding, return to the confirmation email page in the browser and try again.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

• About Discourse
• Discourse on Github
• Discourse Community