discourse/docs/INSTALL-cloud.md

Set up Discourse in the cloud in under 30 minutes with zero knowledge of Rails or Linux shell using our Discourse Docker image. We recommend Digital Ocean, but these steps will work on any Docker-compatible cloud provider or local server.

Create New Cloud Server

Sign up for Digital Ocean, update billing info, then create your new cloud server (Droplet).

• Enter your domain discourse.example.com as the name.

• The default of 1 GB RAM works fine for small Discourse communities. We do recommend 2 GB RAM for medium communities.

• The default of Ubuntu 14.04 LTS x64 works fine. The latest 64-bit LTS distribution is recommended.

• The default of New York is a good choice for most US and European audiences. Or select a region that is geographically closer to your audience.

Create your new Droplet. You will receive a mail from Digital Ocean with the root password to your Droplet. (However, if you know how to use SSH keys, you may not need a password to log in.)

Access Your Cloud Server

Connect to your Droplet via SSH, or use Putty on Windows:

ssh root@192.168.1.1

Replace 192.168.1.1 with the IP address of your Droplet.

You will be asked for permission to connect, type yes, then enter the root password from the email Digital Ocean sent you when the Droplet was set up. You may be prompted to change the root password, too.

Set up Swap (if needed)

• If you're using the minimum 1 GB install, you must set up a swap file.

• If you're using 2 GB+ memory, you can probably get by without a swap file.

Install Docker / Git

wget -qO- https://get.docker.io/ | sh

Install Discourse

Create a /var/discourse folder, clone the Official Discourse Docker Image into it, and make a copy of the config file as app.yml:

mkdir /var/discourse
git clone https://github.com/discourse/discourse_docker.git /var/discourse
cd /var/discourse
cp samples/standalone.yml containers/app.yml

Edit Discourse Configuration

Edit the Discourse configuration at app.yml:

nano containers/app.yml

We recommend Nano because it works like a typical GUI text editor, just use your arrow keys.

• Set DISCOURSE_DEVELOPER_EMAILS to your email address.

• Set DISCOURSE_HOSTNAME to discourse.example.com, this means you want your Discourse available at http://discourse.example.com/. You'll need to update the DNS A record for this domain with the IP address of your server.

• Place your mail credentials in DISCOURSE_SMTP_ADDRESS, DISCOURSE_SMTP_PORT, DISCOURSE_SMTP_USER_NAME, DISCOURSE_SMTP_PASSWORD. Be sure you remove the comment # character and space from the front of these lines as necessary.

• If you are using a 1 GB instance, set UNICORN_WORKERS to 2 and db_shared_buffers to 128MB so you have more memory room.

After completing your edits, press CtrlO then Enter to save and CtrlX to exit.

Email Is Important

Email is CRITICAL for account creation and notifications in Discourse. If you do not properly configure email before bootstrapping YOU WILL HAVE A BROKEN SITE!

• Already have a mail server? Great. Use your existing mail server credentials.

• No existing mail server, or you don't know what it is? No problem, create a free account on Mandrill (or Mailgun, or Mailjet), and use the credentials provided in the dashboard.

• For proper email deliverability, you must set the SPF and DKIM records in your DNS. In Mandrill, that's under Sending Domains, View DKIM/SPF setup instructions.

Bootstrap Discourse

Save the app.yml file, and begin bootstrapping Discourse:

./launcher bootstrap app

This command takes about 8 minutes. It is automagically configuring your Discourse environment.

After that completes, start Discourse:

./launcher start app

Congratulations! You now have your own instance of Discourse!

It should be accessible via the domain name discourse.example.com you entered earlier, provided you configured DNS. If not, you can also visit the server IP directly, e.g. http://192.168.1.1.

Register New Account and Become Admin

There is a reminder at the top about DISCOURSE_DEVELOPER_EMAILS; register a new account via one of those email addresses, and your account will automatically be made an Admin.

(If you don't get any email from your install, and are unable to register a new admin account, please see our Email Troubleshooting checklist.)

You should see Staff topics and the Admin Quick Start Guide. It contains the next steps for further configuring and customizing your Discourse install.

(If you are still unable to register a new admin account via email, see Create Admin Account from Console, but please note that you will have a broken site unless you get email working on your instance.)

Post-Install Maintenance

We strongly suggest you:

• turn on automatic security updates via the dpkg-reconfigure -plow unattended-upgrades command
• enable stronger passwords via the apt-get install libpam-cracklib package

To upgrade Discourse to the latest version, visit /admin/upgrade and follow the instructions.

The launcher command in the /var/discourse folder can be used for various kinds of maintenance:

Usage: launcher COMMAND CONFIG [--skip-prereqs]
Commands:
    start:      Start/initialize a container
    stop:       Stop a running container
    restart:    Restart a container
    destroy:    Stop and remove a container
    enter:      Use nsenter to enter a container
    ssh:        Start a bash shell in a running container
    logs:       Docker logs for container
    mailtest:   Test the mail settings in a container
    bootstrap:  Bootstrap a container for the config based on a template
    rebuild:    Rebuild a container (destroy old, bootstrap, start new)
    cleanup:    Remove all containers that have stopped for > 24 hours

Options:
    --skip-prereqs   Don't check prerequisites
    --docker-args    Extra arguments to pass when running docker

Add More Discourse Features

Do you want...

• Users to log in only via your pre-existing website's registration system? Configure Single-Sign-On.

• Users to log in via Google? (new Oauth2 authentication) Configure Google logins.

• Users to log in via Facebook? Configure Facebook logins.

• Users to log in via Twitter? Configure Twitter logins.

• Users to post replies via email? Configure reply via email.

• Automatic daily backups? Configure backups.

• HTTPS / SSL support? Configure SSL.

• Multiple Discourse sites on the same server? Configure multisite.

• A Content Delivery Network to speed up worldwide access? Configure a CDN. We recommend Fastly.

• Import old content from vBulletin, PHPbb, Vanilla, Drupal, BBPress, etc? See our open source importers

• A firewall on your server? Configure firewall

• To embed Discourse in your WordPress install, or on your static HTML site?

If anything needs to be improved in this guide, feel free to ask on meta.discourse.org, or even better, submit a pull request.