Merge pull request #3131 from anthonybocci/2.4

Create setup documentation

docs/setting-up-cachet.md

@@ -1,3 +0,0 @@
-# Setting up Cachet
-
-This guide will detail how to setup and configure Cachet once you've installed it.

docs/setup/beacons.md

@@ -0,0 +1,31 @@
+# Beacons
+
+> **Version Support**
+> 
+> Beacons will be introduced in v2.4.0
+
+Cachet will periodically communicate with our remote server. This is done so
+that we're able to gather information about the current version of Cachet
+and will later be used for system announcements.
+
+## Disabling the beacon
+
+To disable the beacon, you can turn off the following setting in your .env file.
+
+```
+CACHET_BEACON=false
+```
+
+## What is reported?
+
+We report the following information to our server:
+
+- A unique installation ID
+- The current version of Cachet
+- A support contact email (the first enabled admin's email)
+- Anonymous statistics (the number of users, incidents, components and metrics)
+
+> **Support Contact Email**  
+> The contact email is used for the sole purpose of security
+> announcements and will never be used for anything else.
+

docs/setup/configuring-mail.md

@@ -0,0 +1,66 @@
+# Configuring Mail
+
+Your `.env` file will need to include the following setting keys.
+
+```
+MAIL_DRIVER=smtp
+MAIL_HOST=mailtrap.io
+MAIL_PORT=587
+MAIL_USERNAME=null
+MAIL_PASSWORD=null
+MAIL_ADDRESS=null
+MAIL_NAME=null
+MAIL_ENCRYPTION=tls
+```
+
+After making changes to your mail configuration you'll need to run the
+following command within your Cachet installation directory.
+
+```bash
+$ php artisan config:cache
+
+# If you experience any issues after running this command, run this too:
+$ rm -rf bootstrap/cache/*
+```
+
+## Cachet + Mailgun
+
+Create an account with [Mailgun][1].
+
+MAIL\_USERNAME should be Mailgun domain.
+MAIL\_PASSWORD should be Mailgun API Key.
+
+Edit your `.env` file with the following variables.
+
+```
+MAIL_DRIVER=mailgun
+MAIL_HOST=smtp.mailgun.org
+MAIL_PORT=587
+MAIL_USERNAME=alt-three.com
+MAIL_PASSWORD=xxxx
+MAIL_ADDRESS=support@alt-three.com
+MAIL_NAME="Alt Three Services Limited"
+MAIL_ENCRYPTION=tls
+```
+
+The tls encryption setting is required to have e-mails be properly delivered.
+
+## Cachet + Spark Post
+
+Create an account with [Spark Post][2].
+
+Edit your `.env` file with the following variables.
+
+```
+MAIL_DRIVER=smtp
+MAIL_HOST=smtp.sparkpostmail.com
+MAIL_PORT=587
+MAIL_USERNAME=SMTP_Injection
+MAIL_PASSWORD=API_TOKEN
+MAIL_ADDRESS=support@alt-three.com
+MAIL_NAME="Alt Three Services Limited"
+MAIL_ENCRYPTION=tls
+```
+
+[1]: https://mailgun.com/
+[2]: https://www.sparkpost.com/

docs/setup/configuring-queue.md

@@ -0,0 +1,72 @@
+# Configuring the queue
+
+Cachet uses a queue to send Configuring Mail and Beacons without slowing down
+the rest of the application. This can be setup in a variety of ways.
+
+## Supervisor
+
+The recommended setup for the queue is to use Supervisor.
+
+Supervisor is a process manager which makes managing a number of
+long-running programs a trivial task by providing a consistent interface
+through which they can be monitored and controlled.
+
+## Installations up to Cachet v2.3
+
+`cachet.conf`
+
+```
+[program:cachet-queue]
+command=php artisan queue:work --daemon --delay=2 --sleep=1 --tries=3
+directory=/var/www/cachet/
+redirect\_stderr=true
+autostart=true
+autorestart=true
+user=cachet
+```
+
+## Installations from Cachet v2.4-dev onwards
+
+`cachet.conf`
+
+```
+[program:cachet-queue]
+command=php artisan queue:work --delay=1 --sleep=1 --timeout=1800 --tries=3
+directory=/var/www/cachet/
+redirect\_stderr=true
+autostart=true
+autorestart=true
+user=cachet
+```
+
+> **Update to your configuration!**  
+> Be sure to update the values in the example configuration above to match
+> your installation setup.
+
+## Database Queue with Cron
+
+The default installation of Cachet sets the queue type to database which means
+that all jobs are stored within your database and is then processed by a cron
+job which calls an artisan command from within the project directory.
+
+You'll need to create a new cron job, in Ubuntu it's a case of running
+crontab -e and adding this line:
+
+`* * * * * php /path/to/artisan schedule:run >> /dev/null 2>&1`
+
+Close the file and the cron job will now begin running, processing any
+confirmation and incident emails.
+
+## Synchronous Queue (not recommended for larger installs)
+
+If you cannot add a queue job, another alternative is to process all of
+the jobs immediately after they are created.
+
+> **Not suitable for larger installations!**
+> This setup is not ideal for larger installs with hundreds of subscribers
+> as each email can take a few seconds to send and would slow down your
+> interaction with the system.
+
+To set this up change the .env file with the following setting:
+
+`QUEUE_DRIVER=sync`

docs/setup/configuring-subscribers.md

@@ -0,0 +1,24 @@
+# Configuring Subscribers
+
+Learn how to setup subscribers.
+
+One of the most powerful features of Cachet is the ability to automatically
+send notification emails to anybody who has subscribed to your status
+page whenever an incident is created.
+
+> **Hold up!**  
+> Before going any further, ensure that you've [configured
+> the mail][1] and the [queue][2].
+
+Once you've [Configuring Mail][1], you need to login to your Dashboard and enable
+the Allow people to signup to email notifications? setting found in the
+Application Setup panel.
+
+Once you've enabled this setting you'll see a Subscribe button in the footer
+of your status page:
+
+![Enable subscribers][3]
+
+[1]: configuring-mail.md
+[2]: configuring-queue.md
+[3]: ../images/enable-subscribers.png

docs/setup/cors.md

@@ -0,0 +1,18 @@
+# CORS
+
+Cross-original resource sharing
+
+> **External Access**  
+> By default Cachet can be accessed by any third-party server.
+
+You may configure your Cachet installation for CORS very easily. To blacklist everybody except one or more domains:
+
+- Login to your Dashboard
+- Go to the Settings panel
+- Click on Security
+- You'll see a Allowed domains textarea, fill in any domains that you
+  want to access the API as a comma separated list:
+
+```
+https://demo.cachethq.io,https://status.cachethq.io
+```

docs/setup/installation.md

@@ -4,8 +4,7 @@ This guide will detail how to install Cachet on your server.
 
 ## Download the source code with Git
 
-> **Check out the latest version!**
-> 
+> **Check out the latest version!**  
 > The tags below are examples of what will be shown.
 > You should always run git checkout on the latest tag.
 
@@ -35,14 +34,12 @@ file to `.env` regardless of what environment you're working on.
 
 It's now just a case of editing this new .env file and setting the values of your setup.
 
-> **Environment Configuration Notice**
->
+> **Environment Configuration Notice**  
 > Any values with spaces in them should be contained within double quotes.
 
 The `.env` file set environment variables that will be used by the application.
 
-> **SQLite hosts**
->
+> **SQLite hosts**  
 > If you're using SQLite then your .env file should not contain a
 > `DB_HOST` key. You'll also need to touch ./database/database.sqlite
 > and give it the required permissions.
@@ -61,8 +58,7 @@ composer install --no-dev -o
 If you are installing Cachet as a contributor, you can forget the `--no-dev`
 option.
 
-> **Tip for Windows users**
->
+> **Tip for Windows users**  
 > If you're stuck at the Composer stage, you can run
 > `composer install --no-dev -o --no-scripts`
 > which usually fixes any issues on Windows servers.
@@ -81,8 +77,7 @@ php artisan app:install
 > Never change the `APP_KEY` after installation on production environment.
 > This will result in all of your encrypted/hashed data being lost.
 
-> **Getting a 500 - Internal Server Error?**
->
+> **Getting a 500 - Internal Server Error?**  
 > If you get a 500 error when visiting your status page, you may need to
 > run `chmod -R 777 storage/` for it to work or `rm -rf bootstrap/cache/*`
 
@@ -90,8 +85,7 @@ You can also try to give permissions to cache chmod -R 777 bootstrap/
 
 ## Running Cachet on Apache
 
-> **Required Apache Modules**
->
+> **Required Apache Modules**  
 > You need to enable `mod_rewrite` for Apache. On Debian-based systems you can do this by
 >
 > `sudo a2enmod rewrite`

docs/setup/prerequisites.md

@@ -0,0 +1,40 @@
+# Prerequisites
+
+To start using Cachet, you'll need some prerequisites.
+
+## Application Prerequisites
+
+You'll need at least the following installed on your server:
+
+- PHP 5.5.9, you'll also need `ext-gd`, `ext-simplexml`, `mcrypt`,
+  `ext-xml`, `ext-mbstring` and `ext-tokenizer` installed.
+- [Composer][1]
+- APCu or Redis for caching.
+- A database driver for your DB, such as MySQL, PostgreSQL or SQLite.
+- Git
+
+> **SQLite**  
+> Whilst we support SQLite, we advise not using it for status pages
+> with a high amount of traffic.
+
+> **MySQL Timezone Info**  
+> Ensure your MySQL database has been updated with the correct timezone
+> information. This will ensure that metrics are shown
+> correctly: [https://dev.mysql.com/doc/refman/5.7/en/time-zone-support.html][2]
+
+## Developer prerequisites
+
+If you are looking to contribute to Cachet, thank you! Your help is really
+appreciated! You may need some extra dependencies; depending on what you're looking for.
+
+Our CSS is compiled from SCSS, so to compile this you will need the following:
+
+- Node.js
+- NPM
+- Bower
+- Gulp
+
+
+
+[1]: https://getcomposer.org/
+[2]: https://dev.mysql.com/doc/refman/5.7/en/time-zone-support.html