diff --git a/docs/images/setup/enable-subscribers.png b/docs/images/setup/enable-subscribers.png new file mode 100644 index 00000000..c088c39b Binary files /dev/null and b/docs/images/setup/enable-subscribers.png differ diff --git a/docs/setting-up-cachet.md b/docs/setting-up-cachet.md deleted file mode 100644 index 20bb181c..00000000 --- a/docs/setting-up-cachet.md +++ /dev/null @@ -1,3 +0,0 @@ -# Setting up Cachet - -This guide will detail how to setup and configure Cachet once you've installed it. diff --git a/docs/setup/beacons.md b/docs/setup/beacons.md new file mode 100644 index 00000000..d686a1bd --- /dev/null +++ b/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. + diff --git a/docs/setup/configuring-mail.md b/docs/setup/configuring-mail.md new file mode 100644 index 00000000..63d73498 --- /dev/null +++ b/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/ diff --git a/docs/setup/configuring-queue.md b/docs/setup/configuring-queue.md new file mode 100644 index 00000000..d1bcf766 --- /dev/null +++ b/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` diff --git a/docs/setup/configuring-subscribers.md b/docs/setup/configuring-subscribers.md new file mode 100644 index 00000000..96802f7e --- /dev/null +++ b/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 diff --git a/docs/setup/cors.md b/docs/setup/cors.md new file mode 100644 index 00000000..03ef5fbd --- /dev/null +++ b/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 +``` diff --git a/docs/installation.md b/docs/setup/installation.md similarity index 96% rename from docs/installation.md rename to docs/setup/installation.md index 17301cbe..2db63b30 100644 --- a/docs/installation.md +++ b/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` diff --git a/docs/setup/prerequisites.md b/docs/setup/prerequisites.md new file mode 100644 index 00000000..faf2052a --- /dev/null +++ b/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