Discourse is an open-source discussion platform. It can be used as a mailing list, a discussion forum, or a long-form chat room. In this guide we'll walk you through the steps to install Discourse in an isolated environment using Docker, a containerization application.
Prerequisites
Before we get started, there are a few things we need to set up first:
- One Ubuntu 16.04 server with at least 2GB of RAM
- Docker installed on your Ubuntu server
- A domain name that resolves to your server
- An SMTP mail server. If you don't want to run your own mail server, you can use another service, like a free account on Gmail etc.
Downloading Discourse
With all the prerequisites out of the way, you can go straight to installing Discourse.
You will need to be root through the rest of the setup and bootstrap process, so first, switch to a root shell.
sudo -s
Next, create the /var/discourse directory, where all the Discourse-related files will reside.
mkdir /var/discourse
Finally, clone the official Discourse Docker Image into /var/discourse.
git clone https://github.com/discourse/discourse_docker.git /var/discourse
With the files we need in place, we can move on to configuration and bootstrapping.
Configuring and Bootstrapping Discourse
Move to the /var/discourse directory, where the Discourse files are.
cd /var/discourse
From here, you can launch the included setup script.
./discourse-setup
You will be asked the following questions:
Hostname for your Discourse?
Enter the hostname you'd like to use for Discourse, e.g. discourse.example.com, replacing example.com with your domain name. You do need to use a domain name because an IP address won't work when sending email.
Email address for admin account?
Choose the email address that you want to use for the Discourse admin account. It can be totally unrelated to your Discourse domain and can be any email address you find convenient.
Note that this email address will be made the Discourse admin by default when the first user registers with that email. You'll also need this email address later when you set up Discourse from its web control panel.
SMTP server address?
SMTP user name?
SMTP port?
SMTP password?
Enter your SMTP server details for these questions. If you're using SparkPost, the SMTP server address will be smtp.sparkpostmail.com, the user name will be SMTP_Injection, the port will be 587, and the password will be the API key.
Finally, you will be asked to confirm all the settings you just entered. After you confirm your settings, the script will generate a configuration file called app.yml and then the bootstrap process will start.
Note: If you need to change or fix these settings after bootstrapping, edit your /containers/app.yml file and run ./launcher rebuild app. Otherwise, your changes will not take effect.
Bootstrapping takes between 2-8 minutes, after which your instance will be running! Let's move on to creating an administrator account.
Registering an Admin Account
Visit your Discourse domain in your favorite web browser to view the Discourse web page.
If you receive a 502 Bad Gateway error, try waiting a minute or two and then refreshing; Discourse may not have finished starting yet.
When the page loads, click the blue Register button. You'll see a form entitled Register Admin Account with the following fields:
- Email: Choose the email address you provided earlier from the pull-down menu.
- Username: Choose a username.
- Password: Choose a strong password.
Then click the blue Register button on the form to submit it. You'll see a dialog that says Confirm your Email. Check your inbox for the confirmation email. If you didn't receive it, try clicking the Resend Activation Email button. If you're still unable to register a new admin account, please see the Discourse email troubleshooting checklist.
After registering your admin account, the setup wizard will launch and guide you through Discourse's basic configuration. You can walk through it now or click Maybe Later to skip.
After completing or skipping the setup wizard, you'll see some topics and the Admin Quick Start Guide (labeled READ ME FIRST), which contains tips for further customizing your Discourse installation.
You're all set! If you need to upgrade Discourse in the future, you can do it from the command line by pulling the latest version of the code from the Git repo and rebuliding the app, like this:
cd /var/discourse
git pull
./launcher rebuild app
You can also update it in your browser by visiting http://discourse.example.com/admin/upgrade, clicking Upgrade to the Latest Version, and following the instructions.
Conclusion
You can now start managing your Discourse forum and let users sign up.