initial version of development/clone from git guide

docs/gatekeeper/development/clone-from-git.md

@@ -0,0 +1,79 @@
+# Clone Gatkeeper from git
+This guide is for developers who want to work on Gatekeeper's core code. It will walk you through
+setting up a fresh site instance and cloning a version of Gatekeeper into it from a remote git
+repository.
+
+## Obtain an emergence host
+You will need a host server dedicated to running emergence. If you don't have access to one already,
+the easiest way to get started is to spin up a small **Ubuntu 14.04 LTS** virtual machine with a cloud
+provider like Digital Ocean, Google Cloud Compute, AWS, or countless others. Once you are logged in
+to your fresh Ubuntu 14.04 machine, follow [emergence's installation guide](emr.ge/docs/setup/ubuntu/14.04)
+to prepare it for hosting emergence-powered sites like Gatekeeper.
+
+## Create a site
+Gatekeeper is based on emergence's `skeleton-v2` site template. Unlike when provising a deployment
+instance of Gatekeeper, for development you want to create a site extending Gatekeeper's parent
+site rather than Gatekeeper itself. Gatekeeper's code will be checked out via git, and it would be
+messy to do that on top of another instance (and ossibly different version) of Gatekeeper.
+
+Use emergence's host control panel to create a new site with your desired hostname and initial user, just
+be sure to select `skeleton-v2.emr.ge` as the parent hostname. After the site is created login to <kbd>/develop</kbd>
+with your initial user developer account.
+
+## Configure git link
+To configure a link with a git repository, create a file called <kbd>Git.config.php</kbd> in the top level of the
+`php-config` directory:
+
+```php
+<?php
+
+Git::$repositories['Gatekeeper'] = [
+    'remote' => 'git@github.com:JarvusInnovations/Gatekeeper.git',
+    'originBranch' => 'master',
+    'workingBranch' => 'instances/' . Site::getConfig('primary_hostname'),
+    'localOnly' => true,
+    'trees' => [
+        'dwoo-plugins',
+        'event-handlers',
+        'html-templates',
+        'php-classes',
+        'php-config' => [
+            'exclude' => '#^/Git\\.config\\.php$#' // don't sync this file
+        ],
+        'php-migrations',
+        'phpunit-tests',
+        'sencha-workspace/pages',
+        'site-root' => [
+            'exclude' => [
+                '#^/css(/|$)#', // don't sync /css, this directory is generated by /sass/compile
+                '#^/js/pages(/|$)#' // don't sync /js/pages, this directory is generated by /sencha-cmd/pages-build
+            ]
+        ]
+    ]
+];
+```
+
+You may change `originBranch` to select a different source and change `workingBranch` to change which branch you'll
+be initially setup to commit to (both can be set to the same thing.)
+
+See the [emergence manual page on git integration](http://emr.ge/docs/git/init) for full details on all the configuration
+options. The [latest version of Gatekeeper's Git.config.php](https://github.com/JarvusInnovations/Gatekeeper/blob/master/php-config/Git.config.php)
+is always available on Github.
+
+## Initialize git link
+Visit <kbd>/git/init?repo=Gatekeeper</kbd> to initialize the link with the configured git repository. If you are
+cloning via HTTPS or don't need to push changes back to origin from the web interfaces, you can leave the deploy key field
+empty and skip setting one up. Without a deploy key you will need to SSH into the server and use the git CLI to push changes.
+[Setting up a deploy key](http://emr.ge/docs/git/init) will enable you to use emergence's (currently minimal) web interface
+for commiting/pushing changes.
+
+## Import code from git
+Visit <kbd>/git/import?repo=Gatekeeper</kbd> to pull the git tree into your emergence site.
+
+## Execute initial builds
+Your site will work at this point, but the production views of pages will be missing Gatekeeper's extensions to
+skeleton-v2`s frontend CSS and JS that go through a build process.
+
+- Compile CSS by going to <kbd>/sass/compile</kbd>
+- Compile JS by going to <kbd>/sencha-cmd/pages-build</kbd> (this one will take a while on your first
+run as the ExtJS framework sources are downloaded -- just let it keep spinning and find something else to do for a bit)