add api-paas-failwhale

for use when we don't want API to serve any traffic, but paas is still
running. It's a simple nginx_buildpack app that is pushed separately,
and then two makefile commands that toggle the routes (and also
stop/start the nginx app).

For all endpoints/methods it returns a 503, with the response body.

```
{
    "status_code": 503,
    "errors": [
        {
            "error": "PlannedMaintenanceError",
            "message": "We’re performing some essential updates. Notify will be back shortly. Please check https://status.notifications.service.gov.uk/ for more details"
        }
    ]
}
```

NB: If you hit `/` it'll still return 404 - as this is defined in the
paas-proxy instance on aws.

Makefile

@@ -110,16 +110,19 @@ clean:
 .PHONY: preview
 preview: ## Set environment to preview
 	$(eval export DEPLOY_ENV=preview)
+	$(eval export DNS_NAME="notify.works")
 	@true
 
 .PHONY: staging
 staging: ## Set environment to staging
 	$(eval export DEPLOY_ENV=staging)
+	$(eval export DNS_NAME="staging-notify.works")
 	@true
 
 .PHONY: production
 production: ## Set environment to production
 	$(eval export DEPLOY_ENV=production)
+	$(eval export DNS_NAME="notifications.service.gov.uk")
 	@true
 
 .PHONY: cf-login
@@ -176,3 +179,27 @@ cf-rollback: ## Rollbacks the app to the previous release
 .PHONY: check-if-migrations-to-run
 check-if-migrations-to-run:
 	@echo $(shell python3 scripts/check_if_new_migration.py)
+
+.PHONY: cf-deploy-failwhale
+cf-deploy-failwhale:  #
+	$(if ${CF_SPACE},,$(error Must target space, eg `make preview cf-deploy-failwhale`))
+	cd ./paas-failwhale; cf push notify-api-failwhale -f manifest.yml
+
+.PHONY: enable-failwhale
+enable-failwhale: ## Enable the failwhale app and disable api
+	$(if ${DNS_NAME},,$(error Must target space, eg `make preview enable-failwhale`))
+	# make sure failwhale is running first
+	cf start notify-api-failwhale
+
+	cf map-route notify-api-failwhale ${DNS_NAME} --hostname api
+	cf unmap-route notify-api ${DNS_NAME} --hostname api
+	@echo "Failwhale is enabled"
+
+.PHONY: disable-failwhale
+disable-failwhale: ## Disable the failwhale app and enable api
+	$(if ${DNS_NAME},,$(error Must target space, eg `make preview disable-failwhale`))
+
+	cf map-route notify-api ${DNS_NAME} --hostname api
+	cf unmap-route notify-api-failwhale ${DNS_NAME} --hostname api
+	cf stop notify-api-failwhale
+	@echo "Failwhale is disabled"

paas-failwhale/README.md

@@ -0,0 +1,27 @@
+### What is it?
+
+This is a simple static error page to present to API users in case of a (planned) downtime.
+It is deployed as an individual app and remains dormant until a route is assigned to it.
+It returns a 503 error code and a standard json response for all routes.
+
+
+### How do I use it?
+
+It should already be deployed, but if not (or if you need to make changes to the nginx config) you can deploy it by running
+
+    cf push notify-api-failwhale
+
+To enable it you need to run
+
+    make <environment> enable-failwhale
+
+and to disable it
+
+    make <environment> disable-failwhale
+
+
+Where `<environment>` is any of
+
+- preview
+- staging
+- production

paas-failwhale/manifest.yml

@@ -0,0 +1,8 @@
+---
+
+applications:
+  - name: notify-api-failwhale
+    buildpacks:
+      - nginx_buildpack
+    memory: 256M
+    no-route: true

paas-failwhale/nginx.conf

@@ -0,0 +1,31 @@
+worker_processes 1;
+daemon off;
+
+error_log ./error.log;
+events { worker_connections 8192; }
+
+http {
+  charset utf-8;
+  log_format cloudfoundry '$http_x_forwarded_for - $http_referer - [$time_local] "$request" $status $body_bytes_sent';
+  access_log ./access.log cloudfoundry;
+
+  keepalive_timeout 30;
+  server_tokens off;
+
+  server {
+    listen {{port}};
+    server_name localhost;
+
+    location / {
+        set $RESP '{';
+        set $RESP '${RESP} "status_code": 503,';
+        set $RESP '${RESP} "errors": [ {';
+        set $RESP '${RESP} "error": "PlannedMaintenanceError",';
+        set $RESP '${RESP} "message": "We’re performing some essential updates. Notify will be back shortly. Please check https://status.notifications.service.gov.uk/ for more details"';
+        set $RESP '${RESP} } ] }';
+
+        add_header  Content-Type    application/json;
+        return 503 '$RESP';
+    }
+  }
+}