Add more detailed installation instructions.

README.md

@@ -1,8 +1,13 @@
 # Heighliner
 
+[![Build Status](https://travis-ci.com/manifoldco/heighliner.svg?token=SbTMbCYMT5HWVmmTnBoj&branch=master)](https://travis-ci.com/manifoldco/heighliner)
+[![GoDoc](https://godoc.org/github.com/manifoldco/heighliner?status.svg)](https://godoc.org/github.com/manifoldco/heighliner)
+
 > A Heighliner is truly big. Its hold will tuck all of our frigates and transports
 > into a little corner-we'll be just one small part of the ship's manifest.
 
+Heighliner aims to make your workflow with GitHub and Kubernetes easy.
+
 ## Goals
 
 **Cloud Native.** Instead of templating, Heighliner runs your infrastructure as
@@ -11,7 +16,7 @@ software, keeping the state of your deployments always as they should be.
 **Connected.** The cluster is aware of container registry and source code
 repository state. It reacts to them (creating new deploys), and reflects into
 them (updating GitHub PR deployment status). Preview deploys are automatically
-created and destoryed. Deploys can auto-update based on Semantic Versioning
+created and destroyed. Deploys can auto-update based on Semantic Versioning
 policies, or be manually controlled.
 
 **Complete.** A Heighliner Microservice comes with DNS and TLS out of the box.
@@ -21,32 +26,19 @@ running without much effort, but can be overridded for customization.
 
 ## Installation
 
-Heighliner exists out of multiple components, we've explained these in detail
+Heighliner consists out of multiple components, we've explained these in detail
 in the [design docs](docs/design/README.md).
 
-### Controllers
-
-To install all the controllers, apply the YAML files in the `docs/kube`
-directory.
-
-**Note**: you'll want to update the callbacks URL in the `github-repository`
-controller to a URL you'll use in your cluster.
-
-### GitHub Token
-
-First off, you'll need a GitHub token per repository you want to watch. This
-should then be injected as a secret in your cluster, where the token key is
-`GITHUB_AUTH_TOKEN`.
-
-This secret should live in the same namespace as where you'd like the
-applications to be deployed and where you install the CRDs. It will be used as
-a Local Reference within your `GitHubRepository` CRD.
+For a full installation process, have a look at the [installation docs](docs/installation.md).
 
 ## Usage
 
 ### Configure a GitHub Repository
 
-The github repository resource is used to syncronize releases and pull requests
+Ensure that you have an API token installed in your cluster. Follow our [how to](docs/design/github-connector.md#APIToken)
+for further instructions.
+
+The GitHub repository resource is used to syncronize releases and pull requests
 with cluster state, and update pull requests with deployment status.
 
 ```yaml
@@ -80,7 +72,7 @@ spec:
 ### Configure an Image Policy
 
 The image policy resource syncronizes Docker container images with cluster
-state. It cross references with github releases, filtering out images that do
+state. It cross references with GitHub releases, filtering out images that do
 not match the versioning policy.
 
 ```yaml

docs/design/github-connector.md

@@ -26,7 +26,31 @@ below.
 ### API Token
 
 First, an API token will be needed if a CRD is set up. This [GitHub API Token](https://github.com/settings/tokens)
-should have the `admin:repo_hook` and `repo` permissions. Once you have a token you can manually add it to your secrets in development in the namespace that your app expects. The expected token key is `GITHUB_AUTH_TOKEN`
+should have the `admin:repo_hook` and `repo` permissions. Once you have a token
+you can manually add it to your secrets in development in the namespace that
+your app expects. The expected token key is `GITHUB_AUTH_TOKEN`.
+
+This Token is only needed when installing a new GitHubRepository as it is
+repository bound.
+
+To install a token, go to the [GitHub Personal Access Tokens](https://github.com/settings/tokens) page.
+
+![GitHub API Tokens](github-tokens.png)
+
+On the next page, you'll see the API token, this will be in the format of
+`888fe32217e96eaaa0709c37a488fd4a457015eb`.
+
+With this token, you can now generate a new Kubernetes Secret:
+
+```
+$ kubectl create secret generic github-auth-token --from-literal=GITHUB_AUTH_TOKEN=888fe32217e96eaaa0709c37a488fd4a457015eb
+```
+
+This will put the secret in your cluster in a format Heighliner understands. You
+can now use `github-auth-token` as a reference to the secret.
+
+*Note*: this needs to be installed in the namespace where you install the
+GitHubRepository.
 
 ### Domain
 

docs/installation.md

@@ -0,0 +1,44 @@
+# Installation
+
+In our installation process we've made a few assumptions, these are all about
+what is already installed in your cluster. If your configuration is different,
+it's still possible to install Heighliner, but you might have to change some of
+the installation files found in [docs/kube](./kube).
+
+We've assumed you have the following operators installed in your cluster:
+
+- [Ingress Nginx](https://github.com/kubernetes/ingress-nginx) as an Ingress
+- [Cert Manager](https://github.com/jetstack/cert-manager) for TLS Certificate management
+- [External DNS](https://github.com/kubernetes-incubator/external-dns) for DNS configuration
+
+## Manual Installation
+
+We've templated our installation files so we can install things dynamically. The
+key attributes that should be filled in are:
+
+- **Version**: the version of Heighliner to install
+- **GitHubAPIToken**: the API token to use when communicating with GitHub
+- **DNSProvider**: the DNS provider that is set up with ExternalDNS
+
+### GitHub
+
+The GitHubCallbackURL is used to link the cluster with GitHub. This is further
+described in [the GitHub Connector documentation](./design/github-connector.md#Domain).
+
+We'll also need an [API Token](./design/github-connector.md#APIToken) which will
+allow us to actually communicate with GitHub. This API Token is only needed when
+you install a new GitHubRepository into your cluster.
+
+### Applying the files
+
+Once the attributes are filled in, we can go ahead and apply the files:
+
+```
+$ kubectl apply -f docs/kube
+```
+
+This will set up all the controllers and install the necessary RBAC rules. The
+controllers will then install the CRDs accordingly.
+
+Now that we have Heighliner up and running, we can start installing
+Microservices.