Reorganize README into sections.

README.md

@@ -30,208 +30,26 @@ Streaming is done through a [controller](app/controllers/streams_controller.rb)
 
 * MySQL, Postgresql, or SQLite
 * Memcache
-* Ruby (currently 2.1.1)
+* Ruby (>= 2.1.1)
 * Git (>= 1.7.2)
 
-#### Setup
+### Documentation
 
-Run the bootstrap script to use the test credentials.
-
-```bash
-script/bootstrap
-rails s
-open http://localhost:3000
-```
-
- - Add a new project http://localhost:3000/projects/new
- - name: example-project url: [email protected]:samson-test-org/example-project.git
- - Create a Stage
- - Deploy!
-
-For a real setup:
-
-#### Database
-
-Set up a production block in database.yml with the settings to connect to your DB then run `RAILS_ENV=production bundle exec rake db:setup`
-
-#### Webserver
-
-Configure `config/puma.rb` as you need. See [puma's documentation](https://github.com/puma/puma/) for details. You can start the server using this file by doing `puma -C config/puma.rb`.
-
-#### Environment
-
-Set the following config in your `.env` file:
-
-##### General app (mandatory)
-
-*SECRET_TOKEN* for Rails, generated during script/bootstrap.
-
-##### GitHub token (mandatory)
-
-*GITHUB_TOKEN*
-
-This is a personal access token that Samson uses to access project repositories, commits, files and pull requests.
-
-* Navigate to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new) to generate a new personal access token
-* Choose scope including repo, read:org, user and then generate the token
-* You should now have a personal access token to populate the .env file with
-
-##### GitHub OAuth (mandatory)
-
-*GITHUB_CLIENT_ID* and *GITHUB_SECRET*
-
-* Navigate to [https://github.com/settings/applications/new](https://github.com/settings/applications/new) and register a new OAuth application
-* Set the Homepage URL to http://localhost:3000
-* Set the Authorization callback URL to http://localhost:3000/auth/github/callback
-* You should now have Client ID and Client Secret values to populate the .env file with
-
-##### General app (optional)
-
-*DEFAULT_URL* absolute url to samson (used by the mailer), e.g. http://localhost:3000
-
-##### GitHub organisation and teams (optional)
-
-Samson can use an organisation's teams to provide default roles to users authenticating with GitHub.
-
-*GITHUB_ORGANIZATION* name of the organisation to read teams from, e.g. zendesk
-
-*GITHUB_ADMIN_TEAM* members of this team automatically become Samson admins, e.g. owners
-
-*GITHUB_DEPLOY_TEAM* members of this team automatically become Samson deployers, e.g. deployers
-
-##### GitHub URLs (optional)
-
-Samson can use custom GitHub endpoints if, for example, you are using GitHub enterprise.
-
-*GITHUB_WEB_URL* used for GitHub interface links, e.g. compare screens, OAuth authorization
-
-*GITHUB_API_URL* used for GitHub API access
-
-##### Google OAuth (optional)
-
-*GOOGLE_CLIENT_ID* and *GOOGLE_CLIENT_SECRET*
-
-* Navigate to https://console.developers.google.com/project and create a new project
-* Enter a name and a unique project id
-* Once the project is provisioned, click APIs & auth
-* Turn on Contacts API and Google+ API (they are needed by Samson to get email and avatar)
-* Click the Credentials link and then create a new Client ID
-* Set the Authorized JavaScript Origins to http://localhost:3000
-* Set the Authorized Redirect URI to http://localhost:3000/auth/google/callback
-* Create the Client ID
-* You should now have Client ID and Client secret values to populate the .env file with
-
-##### New Relic integration (optional)
-
-*NEWRELIC_API_KEY*
-
-You may fill in using the instructions below if you would
-like a dynamic chart of response time and throughput during deploys.
-[https://docs.newrelic.com/docs/features/getting-started-with-the-new-relic-rest-api#setup](https://docs.newrelic.com/docs/features/getting-started-with-the-new-relic-rest-api#setup)
-
-#### User roles
-
-Role | Description
---- | ---
-Viewer | Can view all deploys.
-Deployer | Viewer + ability to deploy projects.
-Admin | Deployer + can setup and configure projects.
-Super Admin | Admin + management of user roles.
-
-The first user that logs into Samson will automatically become a super admin.
-
-#### CI support
-
-Samson can be integrated with CI services through webhooks.
-You can find a link to webhook on every project page.
-There are links on webhook pages that you will want to add to your project
-settings on your CI service.
-Set up your webhooks and the deployment process can be automated.
-
-##### Process
-
--> Push to branch(e.g. master)
--> CI validation
--> CI makes webhook call
--> Samson receives webhook call
--> Samson checks if validation is passed
--> Deploy if passed / do nothing if failed
-
-##### Supported services
-
-* Travis
-    * You can add a webhook notification to the .travis.yml file per project
-* Semaphore
-    * Semaphore has webhook per project settings
-    * Add webhook link to your semaphore project
-* Tddium
-    * Tddium only has webhook per organisation setting
-    * However you can have multiple webhooks per organisation
-    * Add all webhooks to your organisation
-    * Samson will match url to see if the webhook call is for the correct project
-* Jenkins
-    * Setup using the [Notification Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Notification+Plugin)
-* Buildkite
-    * You can add a webhook per project under settings/notifications
-    * You can add any value to the 'Token' field, as it is not used
-* Github
-    * You may add a webhook for push events
-
-Skip a deploy:
-
-Add "[deploy skip]" to your commit message, and Samson will ignore the webhook
-from CI.
-
-##### Other
-
-* JIRA
-* Datadog
-* New Relic
-* Flowdock
-* Slack
-* Github
-* [Hipchat](https://github.com/listia/samson_hipchat): Clone of Slack plugin
-
-#### Continuous Delivery & Releases
-
-In addition to automatically deploying passing commits to various stages, you
-can also create an automated continuous delivery pipeline. By setting a *release
-branch*, each new passing commit on that branch will cause a new release, with a
-automatically incrementing version number. The commit will be tagged with the
-version number, e.g. `v42`, and the release will appear in Samson.
-
-Any stage can be configured to automatically deploy new releases. For instance,
-you might want each new release to be deployed to your staging environment
-automatically.
-
-### Instrumentation
-
-Samson sends StatsD basic web request metrics and metrics about deploys and threads
-in use. Statsd silently disables itself if no agent is running on the host. All
-metrics collected are prepending with 'samson.app'.
-
-### Plugins
-
-Samson now supports writing plugins to add functionality to the core app keeping the core isolated and simpler. You can
-thus add UI elements to pages that support it, and hook into events such as before and after deploys.
-
-To get started execute the following and follow the on-screen instructions:
-```
-rails generate plugin MyCoolNewPlugin
-```
-
-Also feel free to browse the existing plugins in the 'plugins' directory to get a feel. They follow the structure of a 
-Rails Engine.
+* [Getting started](docs/setup.md)
+* [Permissions](docs/permissions.md)
+* [Continuous Integration](docs/ci.md)
+* [Extra features](docs/extra_features.md)
+* [Plugins](docs/plugins.md)
+* [Getting statistics](docs/stats.md)
 
 ### Contributing
 
 Improvements are always welcome. Please follow these steps to contribute
 
-1. Submit a Pull Request with a detailed explaination of changes and
-screenshots (if UI is changing)
+1. Submit a Pull Request with a detailed explaination of changes and screenshots (if UI is changing)
 1. Receive a :+1: from a core team member
 1. Core team will merge your changes
 
 ### Team
 
-Core team is [@steved](https://github.com/steved), [@dasch](https://github.com/dasch), [@jwswj](https://github.com/jwswj), [@halcyonCorsair](https://github.com/halcyonCorsair), [@princemaple](https://github.com/princemaple), [@bolddane](https://github.com/bolddane), [@pswadi-zendesk](https://github.com/pswadi-zendesk).
+Core team is [@steved](https://github.com/steved), [@dasch](https://github.com/dasch), [@jwswj](https://github.com/jwswj), [@halcyonCorsair](https://github.com/halcyonCorsair), [@princemaple](https://github.com/princemaple), [@bolddane](https://github.com/bolddane), [@pswadi-zendesk](https://github.com/pswadi-zendesk), [@henders](https://github.com/henders).

docs/ci.md

@@ -0,0 +1,56 @@
+# Continuous Integration support
+
+Samson can be integrated with CI services through web-hooks. Web-hooks are just URLs that add to your 
+favourite CI service to allow it to tell Samson that a new release or deploy should be triggered.
+
+Each project has it's own set of web-hook URLs. You can find a list of them for the various CI services Samson supports on the
+'webhooks' tab when you navigate to your project within Samson.
+
+There are 2 uses of web-hooks in Samson:
+* Create a release for the project within Samson. I.e., Increment a version number, and tag the repo within Github so you can deploy tags instead of 'master'.
+* Automatically trigger a deploy to your target hosts.
+
+You can combine those 2 above as well.
+
+## Workflow Summary
+
+-> Push a change to a branch in Github (e.g. master)
+-> CI validates the change
+-> CI makes webhook call back to Samson
+-> Samson receives webhook call
+-> Samson checks if validation is passed
+-> Deploy if passed / do nothing if failed
+
+## Supported CI Services
+
+* Travis
+    * You can add a webhook notification to the .travis.yml file per project
+* Semaphore
+    * Semaphore has webhook per project settings
+    * Add webhook link to your semaphore project
+* Tddium
+    * Tddium only has webhook per organisation setting
+    * However you can have multiple webhooks per organisation
+    * Add all webhooks to your organisation
+    * Samson will match url to see if the webhook call is for the correct project
+* Jenkins
+    * Setup using the [Notification Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Notification+Plugin)
+* Buildkite
+    * You can add a webhook per project under settings/notifications
+    * You can add any value to the 'Token' field, as it is not used
+* Github
+    * You may add a webhook for push events
+
+Note: to skip a deploy, add "[deploy skip]" to your commit message, and Samson will ignore the webhook from CI.
+
+#### Continuous Delivery & Releases
+
+In addition to automatically deploying passing commits to various stages, you
+can also create an automated continuous delivery pipeline. By setting a *release
+branch*, each new passing commit on that branch will cause a new release, with a
+automatically incrementing version number. The commit will be tagged with the
+version number, e.g. `v42`, and the release will appear in Samson.
+
+Any stage can be configured to automatically deploy new releases. For instance,
+you might want each new release to be deployed to your staging environment
+automatically.

docs/extra_features.md

@@ -0,0 +1,27 @@
+# Extra Features
+
+We have other features that are turned off by default and require setting an environment variable to enable:
+
+## Environment and Deploy Group managing
+
+Enable by setting DEPLOY_GROUP_FEATURE=1
+
+Now you will see extra items in the Admin menu:
+* Admin -> Environments
+** This page allows you to create your deploy environments like 'Production', 'Staging', 'Master', etc...
+* Admin -> Deploy Groups
+** This allows you to model the individual target hosts/groups within the above environments.
+
+When you set those up, you can now edit the Stages within the Projects and tag the appropriate deploy-groups that those 
+stages deploy to.
+
+Now you can use $DEPLOY_GROUPS within the stage commands to target the deploy-groups you've checked the boxes for.
+E.g., in the stage commands you can execute: 'echo "Deploying to $DEPLOY_GROUPS"'
+
+Also you get another main menu item 'Environments'. Navigating to there will show you which versions for your projects are 
+currently deployed to for the various environments and deploy-groups you configured.
+
+Admin screens  | Dashboard screens
+------------- | -------------
+<img src="/docs/images/deploy_group_admin2.png?raw=true" width="300" /> | <img src="/docs/images/deploy_group_dash1.png?raw=true" width="300" />
+<img src="/docs/images/deploy_group_admin.png?raw=true" width="300"> | <img src="/docs/images/deploy_group_dash2.png?raw=true" width="300">

docs/permissions.md

@@ -0,0 +1,11 @@
+# User roles
+
+The first user that logs into Samson will automatically become a super admin.
+You can manage the roles of all your users from the 'Admin' -> 'Users' menu.
+
+Role | Description
+--- | ---
+Viewer | Can view all deploys.
+Deployer | Viewer + ability to deploy projects.
+Admin | Deployer + can setup and configure projects.
+Super Admin | Admin + management of user roles.

docs/plugins.md

@@ -0,0 +1,21 @@
+### Plugins
+
+Samson now supports writing plugins to add functionality to the core app keeping the core isolated and simpler. You can
+thus add UI elements to pages that support it, and hook into events such as before and after deploys.
+
+To get started execute the following and follow the on-screen instructions:
+```
+rails generate plugin MyCoolNewPlugin
+```
+
+Also feel free to browse the existing plugins in the 'plugins' directory to get a feel. They follow the structure of a 
+Rails Engine.
+
+Current Plugins:
+
+* Environment variables per project
+* Flowdock
+* [Hipchat](https://github.com/listia/samson_hipchat): Clone of Slack plugin
+* Jenkins
+* Pipelines
+* Slack