Update readme, explain offline runners

Author: npalm

README.md

@@ -1,12 +1,10 @@
 # Terraform module for scalable self hosted GitHub action runners
 
-> WIP: Module is in development
-
 This [Terraform](https://www.terraform.io/) modules create the required infra structure needed to host [GitHub Action](https://github.com/features/actions) self hosted runners on [AWS spot instances](https://aws.amazon.com/ec2/spot/). All logic required to handle the lifecycle for an action runners is implemented in AWS Lambda functions.
 
 ## Motivation
 
-GitHub Actions `self hosted` runners provides you with a flexible option to run your CI workloads on compute of your choice. Currently there is no option provided to automate the creation and scaling of action runners. This module takes care of creating the AWS infra structure to host action runners on spot instances. And provides lambda modules to orchestrate the lifecycle of the action runners.
+GitHub Actions `self hosted` runners provides you with a flexible option to run your CI workloads on compute of your choice. Currently there is no option provided to automate the creation and scaling of action runners. This module takes care of creating the AWS infra structure to host action runners on spot instances. And provides lambda modules to orchestrate the life cycle of the action runners.
 
 Lambda is chosen as runtime for two major reasons. First it allows to create small components with minimal access to AWS and GitHub. Secondly it provides a scalable setup for minimal costs that works on repo level and scales to organization level. The lambdas will create Linux based EC2 instances with Docker to serve CI workloads that can run on Linux and/or Docker. The main goal is here to support Docker based workloads.
 
@@ -37,12 +35,15 @@ Besides these permissions, the lambdas also need permission to CloudWatch (for l
 Examples are provided in [the example directory](examples/). Please ensure you have installed the following tools.
 
 - Terraform, or [tfenv](https://github.com/tfutils/tfenv).
-- Bash shell or compatible.
-- TODO: building lambda ?
-- AWS cli
+- Bash shell or compatible
+- Docker (optional, to build lambda's without node).
+- AWS cli (optional)
+- Node and yarn (for lambda development).
 
 The module support two main scenarios for creating runners. On repository level a runner will be dedicated to only one repository, no other repository can use the runner. On organization level you can use the runner(s) for all the repositories within the organization. See https://help.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners for more information. Before starting the deployment you have to choose one option.
 
+GitHub workflows will fail immediately if there is no action runner available to host your builds. Since this module supports to scale from 0 and up your builds will fail in case there is no active runner available. So we recommend to create an offline runner with the matching label by default `self-hosted`. Create this runner by just following the GitHub instruction on you local machine. You can stop the process after the step of running the `config.sh`. This offline runner will will ensure you builds will not fail if a runner becomes available within 24 hours.
+
 The setup consists of running Terraform to create all AWS resources and configure the GitHub App. The Terraform module requires configuration from the GitHub App and the GitHub app requires output from Terraform. Therefore you should first create the GitHub App, configure the basics. Then run Terraform and finalize the configuration of the GitHub App afterwards.
 
 ### Setup GitHub App (part 1)
@@ -88,14 +89,15 @@ output "files" {
 }
 ```
 
-Next run `terraform init && terraform apply` as result the lambdas will be download to the same directory.
+Next run `terraform init && terraform apply` as result the lambdas will be download to the same directory. Alternatively you can download the zip artifacts with any other tool of you favour. 
 
+For local development you can build all the lambda's at once using `.ci/build.sh` or per lambda using `yarn`, check the`package.json` for the commands.
 
 Next create a second terraform workspace and initiate the module, see the examples for more details.
 
 ```terraform
 module "runners" {
-  source = "git::https://github.com/philips-labs/terraform-aws-github-runner/"
+  source = "git::https://github.com/philips-labs/terraform-aws-github-runner.git?ref=master"
 
   aws_region = "eu-west-1"
   vpc_id     = "vpc-123"
@@ -107,8 +109,8 @@ module "runners" {
     key_base64     = "base64string"
     id             = "1"
     client_id      = "c-123"
-    client_secret  = "secret"
-    webhook_secret = "secret"
+    client_secret  = "client_secret"
+    webhook_secret = "webhook_secret"
   }
 
   webhook_lambda_zip                = "lambdas-download/webhook.zip"
@@ -125,7 +127,7 @@ terraform init
 terrafrom apply
 ```
 
-Check the terraform output for the API gateway url, which you need in the next step. The lambda for syncing the GitHub distribution will be executed by a trigger via Cloud Watch. To ensure the binary is cached, trigger the `runner-binaries-syncer` manually. The payload does not matter.
+Check the terraform output for the API gateway url (endpoint), which you need in the next step. The lambda for syncing the GitHub distribution will be executed by a trigger via Cloud Watch. To ensure the binary is cached, trigger the `runner-binaries-syncer` manually. The payload does not matter. (e.g. `aws lambda invoke --function-name <environment>-syncer  respone.json`)
 
 ### Setup GitHub App (part 2)
 
@@ -136,9 +138,12 @@ Go back to the GitHub App and update the following settings.
 3. Provide the webhook secret.
 4. Enable the `Check run` event for the webhook.
 
+You are now ready to run action workloads on self hosted runner, remember builds will fail if there is no runner available with matching labels. 
 
 ## Examples
 
+TODO
+
 ## Inputs
 
 | Name                                      | Description                                                                                                         | Type                                                                                                                                                                                   | Default                 | Required |
@@ -169,8 +174,6 @@ Go back to the GitHub App and update the following settings.
 | runners          | n/a         |
 | webhook          | n/a         |
 
-
-
 ## Philips Forest
 
 This module is part of the Philips Forest.