Start Here: Installing Discourse with dashboard

Howto
1

Installing Discourse with Literate Computing’s dashboard

To install Discourse, you need 3 things:

  • A domain name that you control and can add A, TXT, and MX records for. You usually manage your DNS settings at the same place you bought it.
  • A Virtual Machine. The Dashboard will create a Digital Ocean droplet for you.
  • An email delivery service. The Dashboard will configure Mailgun for you.

Unless you have specific needs to use something other than Digital Ocean and Mailgun (you would know if you did), you should create those accounts now, and then log in here. The Dashboard will guide you through the steps required to get the API keys and install Discourse. It is much easier to see what you need and how to get it after you log in.

What happens after the installlation is complete?

After the installation is complete, you can use dashboard to accomplish tasks that would otherwise require using an SSH client (or the Digital Ocean console) and typing commands. Some upgrades require logging into the Linux shell and typing “./launcher rebuild app”. Adding and removing plugins requires editing a text file to add or remove the git clone command that loads the plugin. With the Dashboard, you can do these things with a few clicks, but since everything is standard about your installation, you can still do things via the command line if you prefer.

Can I use a different hosting service?

If whatever hosting service you have includes cPanel or Plesk, the answer is “not very easily, and not with dashboard.”

You need a real VM with shell access, root privileges, and the ability to install and run Docker. You should be able to run docker run hello-world and see the “Hello from Docker!” response. If you are not sure about anything in the previous sentences, you should use Digital Ocean. The dashboard will even create your droplet for you.

Can I use a different email delivery service?

You can, but you are on your own for getting it and the required DNS entries properly configured, providing SMTP credentials, and the address that Discourse can use to send its emails.

Purchasing a New Installation

If you are not familiar with installing Discourse, these instructions should answer some questions. The various links here (e.g., to where to get API keys and such) are presented when you need them during the process, so if the information below makes sense to you, you should be able to get going now! (And if not, please let us know by posting here.

Here are the steps:

  • Create an account here and log in.

  • Use this link to create a Digital Ocean account if you do not have one already. That referral link will give you a $100/60 day credit. When you have validated your email address and entered your credit card, go to the API Page and generate a token. Leave that page open or copy the token so you can use it here later.

  • Create your account at Mailgun and visit settings/API keys to retrieve your Private API Key

Once you have gotten done that, dashboard should help you figure out the rest, and if you log in now and give it a try you can probably finish before you read the rest of this topic, but here is what you will do:

  • Enter your desired hostname. It is recommended that you use a subdomain like “forum” or “www” rather than the bare domain. See https://www.yes-www.org/why-use-www/ and http://forcewww.com/ for more information.)

  • Go to the Digital Ocean API page and click the Generate New Token button to generate a new API key (if you do not still have it available). After you generate it, you’ll copy and paste the token into the Digital Ocean API key field on the server page.

  • Similarly, get your Mailgun Private API key from the Settings/API Keys link on the nav bar. (It does not need to be re-generated–there is only one.) Paste it in to the the appriate field.

  • Choose a droplet size. Many people get by with the $5/month 1GB option, but I recommend the $12/month AMD servers if you can afford it.

  • When you have filled in the required information the Install on new droplet button will appear and you can click it to initiate the installation.

  • After a minute or two you will receive an email with DNS instructions. (There are too many DNS providers to support them all, but if you manage your DNS with Digital Ocean or Cloudflare and have a bit of patience for trying new interfaces, send @pfaffman a PM.)

  • When the DNS records have been created and Mailgun approves your domain, the installation will continue. It takes about 15 minutes. When it is complete you’ll see that the task has finished and you’ll receive an “Your Discourse Installation is complete!” email.

You now have an official supported install as described here!

Once that it done, you can use dashboard to add/remove plugins, perform command line upgrades (using exactly the same ./launcher rebuild app command that you will see on meta.discourse.org), set Environment variables to override Discourse settings and more.