Improve installation instructions

* Clarify the requirements for running Pa11y Dashboard, and specifically the versions of MongoDB supported
* Split the installation process in sections so it's easy to follow
* Instead of trying to cover the MongoDB installation on the Readme, refer to the MongoDB docs, but still including a macOS example for easy reference
* Clarify the use of the config files and how they relate to the NODE_ENV variable
* Use a slightly less informal language in a few places

README.md

@@ -16,13 +16,11 @@ Pa11y Dashboard is a web interface to the [Pa11y][pa11y] accessibility reporter;
 
 Pa11y Dashboard is a [Node.js][node] application and requires a stable or LTS version of Node, currently version 8 or greater.
 
-Pa11y Dashboard also requires a [MongoDB][mongo] database to be available so it can store the results of the tests. The database doesn't have to be in the same server or computer where Pa11y Dashboard is running from.
+Pa11y Dashboard uses a [MongoDB][mongo] database to store the results of the tests. The database doesn't have to be in the same server or computer where Pa11y Dashboard is running from.
 
-Since version 3, Pa11y Dashboard uses Headless Chrome in order to run the tests. This means that additional dependencies maybe be required.
+Pa11y Dashboard uses [puppeteer](https://www.npmjs.com/package/puppeteer) to create a headless instance of the Chromium browser in order to run the tests. On certain environments this may require additional dependencies to be installed. For example, in Debian/Ubuntu systems you may need to install the `libnss3` and `libgconf-2-4` libraries in order to be able to run tests on Pa11y Dashboard. Please refer to the documentation from your provider for details on how to do this.
 
-In [Unix-like](https://en.wikipedia.org/wiki/Unix-like) systems you may need to install the `libnss3` and `libgconf-2-4` libraries in order to be able to run Chrome. If you're trying to run the app in a headless environment (e.g. the cloud, or a headless server), you may also need to configure Xvfb before. Please refer to the documentation from your provider for details on how to do this.
+## Setting up Pa11y Dashboard
-
-## Setup
 
 In order to run Pa11y Dashboard, we recommend cloning this repository locally:
 
@@ -37,11 +35,43 @@ cd pa11y-dashboard
 npm install
 ```
 
-You'll also need to have [MongoDB][mongo] installed and running. For quick access, you can install via a package manager such as on Mac OS `brew install mongodb` or on Linux (Debian) it would be `apt-get install mongodb`. To run MongoDB, you can run `mongod` in the command line. See the [MongoDB install guide][mongo-install] for more detailed information.
+### Installing MongoDB
 
-The last step before being able to run the application is to define a configuration for it. This can be done in two ways:
+Instructions for installing and running MongoDB are outside the scope of this document. When in doubt, please refer to the [MongoDB installation instructions](https://docs.mongodb.com/manual/installation/) for details of how to install and run MongoDB on your specific operating system. An example of the installation and configuration process for macOS follows.
 
-### Option 1: Using Environment Variables
+Pa11y Dashboard currently uses version `2.2` of the Node.js MongoDB driver, which means that [only MongoDB servers of versions 3.4 or older are supported](https://docs.mongodb.com/drivers/node/compatibility/). Please ensure that your MongoDB server fills the requirements before trying to run Pa11y Dashboard.
+
+#### Example MongoDB installation for macOS
+
+On recent versions of macOS (10.13 or later), you can use [Homebrew](https://brew.sh/) to install MongoDB 3.4 Community Edition. More recent versions of MongoDB are untested and unsupported.
+
+Tap the MongoDB Homebrew Tap:
+```sh
+brew tap mongodb/brew
+```
+
+Install the Community version of MongoDB:
+```sh
+brew install mongodb-community@3.4
+```
+
+Start the MongoDB server:
+```sh
+brew services start mongodb/brew/mongodb-community
+```
+
+Check that the service has started properly:
+```sh
+$ brew services list
+Name              Status  User       Plist
+mongodb-community started pa11y      /Users/pa11y/Library/LaunchAgents/homebrew.mxcl.mongodb-community.plist
+```
+
+### Configuring Pa11y Dashboard
+
+The last step before being able to run Pa11y Dashboard is to define a configuration for it. This can be done in two ways:
+
+#### Option 1: Using environment variables
 
 Each configuration can be set with an environment variable rather than a config file. For example to run the application on port `8080` you can use the following:
 
@@ -49,11 +79,17 @@ Each configuration can be set with an environment variable rather than a config
 PORT=8080 node index.js
 ```
 
-The [available configurations are documented here](#configurations).
+The [available configurations](#configurations) are documented in the next section.
 
-### Option 2: Using Config Files
+#### Option 2: Using config files
 
-You'll need to copy and modify different config files depending on your environment (set with `NODE_ENV`):
+You can store the configuration for Pa11y Dashboard on a JSON file. You can use a different configuration file for each environment you're planning to run Pa11y Dashboard on. You can choose a specific environment to run the application from by setting the `NODE_ENV` environment variable:
+
+```sh
+NODE_ENV=development node index.js
+```
+
+Three example files are provided in this repository, you can copy and customise them to your liking:
 
 ```sh
 cp config/development.sample.json config/development.json
@@ -61,35 +97,32 @@ cp config/production.sample.json config/production.json
 cp config/test.sample.json config/test.json
 ```
 
-Each of these files defines configurations for a different environment. If you're just running the application locally, then you should be OK with just development and test configurations. The [available configurations are documented here](#configurations).
+The [available configurations](#configurations) are documented in the next section.
 
-Now that you've got your application configured, make sure you have a MongoDB server running with the `mongod` command in another terminal window. You can run in each mode by changing the `NODE_ENV` environment variable:
+If you run into problems, check the [troubleshooting guide][TROUBLESHOOTING.md].
-
-```sh
-NODE_ENV=development node index.js
-```
-
-See [Contributing](#contributing) for more information about running locally (and restarting automatically when files change).
-
-If you run into problems, check the [troubleshooting guide][troubleshooting].
 
 ## Configurations
 
 The boot configurations for Pa11y Dashboard are as follows. Look at the sample JSON files in the repo for example usage.
 
 ### port
+
 *(number)* The port to run the application on. Set via a config file or the `PORT` environment variable.
 
 ### noindex
+
 *(boolean)* If set to `true` (default), the dashboard will not be indexed by search engines. Set to `false` to allow indexing. Set via a config file or the `NOINDEX` environment variable.
 
 ### readonly
+
 *(boolean)* If set to `true`, users will not be able to add, delete or run URLs (defaults to `false`). Set via a config file or the `READONLY` environment variable.
 
 ### siteMessage
+
 *(string)* A message to display prominently on the site home page. Defaults to `null`.
 
 ### webservice
+
 This can either be an object containing [Pa11y Webservice configurations][pa11y-webservice-config], or a string which is the base URL of a [Pa11y Webservice][pa11y-webservice] instance you are running separately. If using environment variables, prefix the webservice vars with `WEBSERVICE_`.
 
 ## Contributing
@@ -143,15 +176,11 @@ Copyright © 2013–2020, Team Pa11y and contributors
 
 [gpl]: http://www.gnu.org/licenses/gpl-3.0.html
 [mongo]: http://www.mongodb.org/
-[mongo-install]: https://docs.mongodb.org/manual/installation/
 [node]: http://nodejs.org/
 [pa11y]: https://github.com/pa11y/pa11y
 [pa11y-webservice-config]: https://github.com/pa11y/webservice#configurations
-[phantom]: http://phantomjs.org/
-[sidekick-proposal]: https://github.com/pa11y/sidekick/blob/master/PROPOSAL.md
 [travis]: https://travis-ci.org/pa11y/dashboard
 [travis-img]: https://travis-ci.org/pa11y/dashboard.png?branch=master
-[troubleshooting]: https://github.com/pa11y/dashboard/blob/master/TROUBLESHOOTING.md
 
 [info-node]: package.json
 [info-build]: https://travis-ci.org/pa11y/pa11y-dashboard