Talk to Frank Beta

Dependencies

nodejs version 10.13.0

Building

To build files to ./dist:

grunt build

Environment Vars

The BUILD_CONFIG=staging|production|development (defaults to development) environment variable should be used to define to the application the environment it is running in. This is separate to NODE_ENV since many libraries (React included) rely on the de-facto standard values of production|development to optimise their running.

Setting BUILD_CONFIG sets NODE_ENV automatically accordingly in webpack.js.

Live configuration

No passwords / keys etc. are kept in the repo. Conmfiguration files (config.<ENV>.yaml) need additional configuration that is read in at runtime.

As such, a number of config.*.yaml files are required in the root of the project to store keys etc.

The following files are required:

config.creds.yaml
config.ethereal.yaml
config.google.yaml
config.mailgun.yaml
config.sentry.yaml
config.webhooksecretkey.yaml

Development

A feature branch branching strategy is in use, specifically:

When a new feature is to be added, a developer should branch from develop naming the new branch feature/[userstory-id]-[short description of new feature for humans]
When the work is ready (tested, linted etc.), a pull request should be opened against the develop branch.
A peer review should be undertaken against the pull request and the branch merged.
The CI server will build from the develop and deploy to the staging server.

Grunt tasks

Task	Description
`grunt` (default)	Clean existing & build new bundled files. Run your app on the development server at `localhost:3000`.
`grunt build`	Create new bundled files
`grunt ngrok`	Setup an grok tunnel to your local web server
`grunt contentful`	Pull all entries from contentful & reindex in Elasticsearch
`grunt localtunnel or grunt ngrok`	Run local server (monitor for changes) with ngrok tunnel

Contenftul CLI

Migration and API query tools available using contentful-cli.

`contentful <script>`	Description
`login / logout`	Start/end a CLI tool session
`content-type list --space-id xxx`	List all content types
`content-type get --space-id xxx --id [content type id]`	Get a list of content type fields

Workbox (service worker)

Note: service workers require an HTTPS connection

Workbox is used to handle service-worker logic. Configuration is found in /workbox-config.js

service worker is found in app/client
all requests for png, ico, css and png files are routed via the service worker using a 'Network first' policy:
- requests made while online will always go to the server first
- offline requests will correctly load the cached files so that offline.html can be loaded correctly
the page at '/offline' is precached when a user first visits the site. This page is then served to users when they go offline via the service worker.
when updating the offline page, the service worker cached version can be invalidated by updating the corresponding 'revision' value in the workbox.precaching.precacheAndRoute options within service-worker.js

Emails

ethereal.email is used for testing emails.

To use the Mailgun testing sandbox, you first need to add your email address to this page (which isn't shown on the dashboard): https://app.mailgun.com/app/account/authorized

Elasticsearch

AWS Elasticsearch is used to provide the search capability, access is restricted using AWS IAM accounts:

The Alpha server has been given the IAM Role 'TalkToFrank-EC2-ElasticSearch' and therefore credentials are auto loaded
For development add the following to your config file, requesting the access key id/secrets where required.

elasticsearch:
  host: ''
  amazonES:
    credentials:
      accessKeyId: ''
      secretAccessKey: ''
    region: ''

Sentry logging

Server side logging via Sentry can be enabled using the following configuration:

sentry:
 logErrors: true
 dsn: ''

Testing

Smoke tests available using cucumber-js and puppeteer. Folder structure for the tests:

.
└── features                        # Folder containing all cucumber feature files
    ├── debug                       # Debugging console output and screenshots saved here
    ├── step_definition             #
    │   ├── common.js               # Cucumber give/then/when step defintions
    ├── support                     # Helper files
    │   ├── actions.js              # Implementations of step definitions using puppeteer API
    │   ├── assertions.js           # Text found on the site used to assert scenarios
    │   ├── pages.js                # URLs used as part of the scenariuos
    │   ├── scope.js                # initialises a global scope used to store access to the browser
    │   └── selectors.js            # DOM selectors found on the site used to assert scenarios
    ├── hooks.js                    # Before/After cucumber hooks
    └── world.js                    # Global cucmber js config

Tags used

@wip - work in progress, to be implemented
@duplicate - should be ignored / are not implemented as the functionality is duplicated into another scenario
@ignore - any other tests that should not be run (aren't going to be implemented and are not duplicates)

Running the test

To run the cucumber-js test the site must already be running, i.e. this command does not start the server. You can either run the tests via the CLI:

CUCUMBER_HOST=[http://testdomain] cucumber-js --tags "not @ignore and not @wip and not @duplicate"

Or using Grunt, which assumes the config found in ./grunt/cucumberjs:

CUCUMBER_HOST=[http://testdomain] grunt cucumberjs

This will create an HTML formatted results page at ./features/report.html

Releasing

Determine the new semantic version of the release.
if updating the offline page content, change the 'revision' number in app/client/service-worker.js to invalidate existing caches
Update package.json.
Ensure changelog is up to date, whereby changes for the release are listed underneath the version.
Merge develop into master.
Manually run the CI server so that the master is deployed to production.
Create a new release/vX.Y.Z where the release number relates to the semantic version of the release.

CI

BuddyCI is used for the CI server (see buddy.yaml).

The Build CI task validates all branches
The Build & Deploy task runs whenever an update to develop is made. This task will update the staging server.

SSH / Keys

To give BuddyCI access to the integration server, the public key (found at /environment-variables) should be added to the deploy user's ~/.ssh/authorized_keys file on the staging server.

UKHSA-Internal/talktofrank-beta