discourse/docs/INSTALL-cloud.md

161 lines
9.3 KiB
Markdown
Raw Normal View History

2017-01-06 22:31:08 -05:00
**Set up Discourse in the cloud in under 30 minutes** with zero knowledge of Rails or Linux shell. We recommend [DigitalOcean][do], but these steps will work on any **Docker-compatible** cloud provider or local server.
2017-01-06 17:14:18 -05:00
> 🔔 Don't have 30 minutes to set this up? For a flat one-time fee of $99, the community can install Discourse in the cloud for you. [Click here to purchase a self-supported community install](https://www.literatecomputing.com/product/discourse-install/).
2016-10-13 16:23:44 -04:00
2016-04-29 06:41:58 -04:00
### Create New Cloud Server
[Sign up for DigitalOcean][do], update billing info, then create your new cloud server.
2015-03-31 17:38:29 -04:00
- Enter your domain `discourse.example.com` as the name.
2015-09-23 06:16:03 -04:00
- The default of **1 GB** RAM works fine for small Discourse communities. We recommend 2 GB RAM for larger communities.
2016-10-22 17:51:17 -04:00
- The default of **Ubuntu 16.04 LTS x64** works fine. At minimum, a 64-bit Linux OS with a kernel version of 3.10+ is required.
2015-03-31 17:38:29 -04:00
- 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.
2015-03-31 17:31:04 -04:00
2016-04-29 06:33:21 -04:00
Create your new Droplet. You will receive an email with the root password. (However, if you know [how to use SSH keys](https://www.google.com/search?q=digitalocean+ssh+keys), you may not need a password to log in.)
2016-04-29 06:41:58 -04:00
### Access Your Cloud Server
2016-04-28 18:03:09 -04:00
Connect to your server via its IP address using SSH, or [Putty][put] on Windows:
ssh root@192.168.1.1
Enter the root password from the email DigitalOcean sent you when the server was set up. You will be prompted to change the root password.
2016-04-27 19:50:46 -04:00
<img src="https://www.discourse.org/images/install/15/ssh-login-terminal.png" width="600px">
2016-04-29 06:41:58 -04:00
### Install Docker / Git
2015-04-22 00:52:21 -04:00
wget -qO- https://get.docker.com/ | sh
2016-04-27 19:03:43 -04:00
This command installs the latest versions of Docker and Git on your server. Alternately, you can manually [install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and the [Docker package for your OS](https://docs.docker.com/installation/).
2016-04-29 06:41:58 -04:00
### Install Discourse
2016-04-27 06:11:45 -04:00
Create a `/var/discourse` folder, clone the [Official Discourse Docker Image][dd] into it:
2016-03-10 03:07:09 -05:00
sudo -s
mkdir /var/discourse
git clone https://github.com/discourse/discourse_docker.git /var/discourse
cd /var/discourse
You will need to be root through the rest of the setup and bootstrap process.
2016-03-10 02:29:43 -05:00
2016-10-22 20:29:20 -04:00
### Email
> ⚠️ **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? Check out our [**Recommended Email Providers for Discourse**][mailconfig].
2017-03-06 15:36:13 -05:00
- To ensure mail deliverability, you must add valid [SPF and DKIM records](https://www.google.com/search?q=spf+dkim) in your DNS. See your mail provider instructions for specifics.
2016-10-22 20:29:20 -04:00
2016-04-29 06:41:58 -04:00
### Edit Discourse Configuration
2016-04-27 06:11:45 -04:00
Launch the setup tool at
2016-04-27 06:11:45 -04:00
./discourse-setup
2016-04-27 06:11:45 -04:00
Answer the following questions when prompted:
2016-04-27 06:11:45 -04:00
Hostname for your Discourse? [discourse.example.com]:
Email address for admin account? [me@example.com]:
SMTP server address? [smtp.example.com]:
SMTP user name? [postmaster@discourse.example.com]:
2016-06-17 16:49:34 -04:00
SMTP port [587]:
2016-04-27 06:11:45 -04:00
SMTP password? []:
2016-10-22 20:29:20 -04:00
This will generate an `app.yml` configuration file on your behalf, and then kicks off bootstrap. Bootstrapping takes between **2-8 minutes** to set up your Discourse. If you need to change or fix these settings after bootstrapping, edit your `/containers/app.yml` file and `./launcher rebuild app`, otherwise your changes will not take effect.
2016-03-10 02:42:03 -05:00
2016-04-29 06:41:58 -04:00
### Start Discourse
2016-04-27 17:45:41 -04:00
Once bootstrapping is complete, your Discourse should be accessible in your web browser via the domain name `discourse.example.com` you entered earlier, provided you configured DNS. If not, you can visit the server IP directly, e.g. `http://192.168.1.1`.
2016-10-22 17:53:54 -04:00
<img src="https://www.discourse.org/images/install/17/discourse-congrats.png" width="650">
2016-04-29 06:41:58 -04:00
### Register New Account and Become Admin
2016-04-27 06:48:26 -04:00
Register a new admin account using one of the email addresses you entered before bootstrapping.
2016-10-22 17:53:54 -04:00
<img src="https://www.discourse.org/images/install/17/discourse-register.png" width="650">
2016-10-22 17:53:54 -04:00
<img src="https://www.discourse.org/images/install/17/discourse-activate.png" width="650">
(If you are unable to register your admin account, check the logs at `/var/discourse/shared/standalone/log/rails/production.log` and see our [Email Troubleshooting checklist](https://meta.discourse.org/t/troubleshooting-email-on-a-new-discourse-install/16326).)
2016-10-22 17:55:34 -04:00
After registering your admin account, the setup wizard will launch and guide you through basic configuration of your Discourse.
2016-10-22 17:53:54 -04:00
<img src="https://www.discourse.org/images/install/17/discourse-wizard-step-1.png" width="650">
2016-10-22 17:55:34 -04:00
After completing the setup wizard, you should see Staff topics and **READ ME FIRST: Admin Quick Start Guide**. This guide contains advice for further configuring and customizing your Discourse install.
<img src="https://www.discourse.org/images/install/17/discourse-homepage.png">
2016-04-29 06:41:58 -04:00
### Post-Install Maintenance
2016-06-17 17:03:52 -04:00
- We strongly suggest you turn on automatic security updates for your OS. In Ubuntu use the `dpkg-reconfigure -plow unattended-upgrades` command.
2016-06-17 16:49:34 -04:00
- If you are using a password and not a SSH key, be sure to enforce a strong root password. In Ubuntu use the `apt-get install libpam-cracklib` package. We also recommend `apt-get install fail2ban` which will default block any IP addresses for 10 minutes that attempt more than 3 password retries.
2016-06-17 17:03:52 -04:00
- If you need or want a default firewall, [turn on ufw](https://meta.discourse.org/t/configure-a-firewall-for-discourse/20584).
2015-09-23 06:26:41 -04:00
You will get email reminders as new versions of Discourse are released. Please stay current to get the latest features and security fixes. To **upgrade Discourse to the latest version**, visit `/admin/upgrade` in your browser and click the Upgrade button.
The `launcher` command in the `/var/discourse` folder can be used for various kinds of maintenance:
```
2016-04-28 18:03:09 -04:00
Usage: launcher COMMAND CONFIG [--skip-prereqs] [--docker-args STRING]
Commands:
start: Start/initialize a container
stop: Stop a running container
restart: Restart a container
destroy: Stop and remove a container
2016-04-28 18:03:09 -04:00
enter: Use nsenter to get a shell into a container
logs: View the Docker logs for 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:
2016-04-28 18:03:09 -04:00
--skip-prereqs Don't check launcher prerequisites
--docker-args Extra arguments to pass when running docker
```
2016-04-29 06:41:58 -04:00
### Add More Discourse Features
Do you want...
* Users to log in *only* via your pre-existing website's registration system? [Configure Single-Sign-On](https://meta.discourse.org/t/official-single-sign-on-for-discourse/13045).
2016-04-28 18:03:09 -04:00
- Users to log in via [Google](https://meta.discourse.org/t/configuring-google-oauth2-login-for-discourse/15858), [Twitter](https://meta.discourse.org/t/configuring-twitter-login-for-discourse/13395), [GitHub](https://meta.discourse.org/t/configuring-github-login-for-discourse/13745), or [Facebook](https://meta.discourse.org/t/configuring-facebook-login-for-discourse/13394)?
2015-09-14 10:43:22 -04:00
- Users to post replies via email? [Configure reply via email](https://meta.discourse.org/t/set-up-reply-via-email-support/14003).
- Automatic daily backups? [Configure backups](https://meta.discourse.org/t/configure-automatic-backups-for-discourse/14855).
2016-03-29 18:26:47 -04:00
2016-05-09 18:18:35 -04:00
- Free HTTPS / SSL support? [Configure Let's Encrypt](https://meta.discourse.org/t/setting-up-lets-encrypt-cert-with-discourse-docker/40709). Paid HTTPS / SSL support? [Configure SSL](https://meta.discourse.org/t/allowing-ssl-for-your-discourse-docker-setup/13847).
2017-01-06 17:14:18 -05:00
- Use a plugin [from Discourse](https://github.com/discourse) or a third party? [Configure plugins](https://meta.discourse.org/t/install-a-plugin/19157)
- Multiple Discourse sites on the same server? [Configure multisite](https://meta.discourse.org/t/multisite-configuration-with-docker/14084).
2017-01-06 17:14:18 -05:00
- Webhooks when events happen in Discourse? [Configure webhooks](https://meta.discourse.org/t/setting-up-webhooks/49045).
- A Content Delivery Network to speed up worldwide access? [Configure a CDN](https://meta.discourse.org/t/enable-a-cdn-for-your-discourse/14857). We recommend [Fastly](http://www.fastly.com/).
2016-04-28 18:03:09 -04:00
- Import old content from vBulletin, PHPbb, Vanilla, Drupal, BBPress, etc? [See our open source importers](https://github.com/discourse/discourse/tree/master/script/import_scripts).
2016-06-04 05:23:04 -04:00
- A user friendly [offline page when rebuilding or upgrading?](https://meta.discourse.org/t/adding-an-offline-page-when-rebuilding/45238)
- To embed Discourse [in your WordPress install](https://github.com/discourse/wp-discourse), or [on your static HTML site](https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963)?
2015-09-23 06:16:03 -04:00
Help us improve this guide! Feel free to ask about it on [meta.discourse.org][meta], or even better, submit a pull request.
[dd]: https://github.com/discourse/discourse_docker
[ssh]: https://help.github.com/articles/generating-ssh-keys
[meta]: https://meta.discourse.org
[do]: https://www.digitalocean.com/?refcode=5fa48ac82415
[put]: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
2016-03-12 02:15:05 -05:00
[mailconfig]: https://github.com/discourse/discourse/blob/master/docs/INSTALL-email.md