@financial-times/n-gage

⚠️ n-gage is unsupported. FT.com projects should migrate to Tool Kit.
n-gage gives a standard set of make tasks and the ngage CLI to help set up, build and deploy projects.

Requirements

• Node version defined by .nvmrc (run command nvm use to switch your local Node version to the one in this file).
• Vault

Installation

git clone git@github.com:Financial-Times/n-gage.git
cd n-gage
make install

Development

Testing

In order to run the tests locally you'll need to run:

make test

Install from NPM

npm install --save-dev --no-package-lock @financial-times/n-gage

Usage

Create a new Makefile file with the following:

# This task tells `make` how to 'build' n-gage. It npm installs n-gage, and
# Once that's done it overwrites the file with its own contents - this
# ensures the timestamp on the file is recent, so `make` won't think the file
# is out of date and try to rebuild it every time
node_modules/@financial-times/n-gage/index.mk:
	npm install --no-save @financial-times/n-gage
	touch $@

# If, by the end of parsing your `Makefile`, `make` finds that any files
# referenced with `-include` don't exist or are out of date, it will run any
# tasks it finds that match the missing file. So if n-gage *is* installed
# it will just be included; if not, it will look for a task to run
-include node_modules/@financial-times/n-gage/index.mk

Make tasks

| Task | Description | |-|-| | a11y | Run automated accessibility tests | | build | Build the repository | | build-production | Build the repository for production | | clean | Git clean the repository | | deploy-assets | Uploads static files such as CSS and JS to S3 | | deploy-production | Deploy staging to production eu and us apps. Also scale down canary app | | deploy-canary | Deploy canary app to staging | | deploy-staging | Deploy the app to staging | | deploy-promote | Promote the staging app to production | | deploy | Deploy the app to heroku | | .env | Downloads environment variables from Vault | | fix-lintspaces | Autofix common lintspaces issues | | help | Show this help message | | init | Clean the repository and start from a fresh build | | install | Install dependencies and copy common dotfiles | | test-review-app | Create and test a review app on heroku.

To override custom environment variables when running nht configure, add:
REVIEW_APP_CONFIGURE_OVERRIDES="NODE_ENV=branch,OTHER_VAR=something"
to the Makefile | | smoke | Run smoke tests on the local or review app, by setting the TESTURL environment variable | | verify | Check files for linting errors | | watch | Watch for static asset changes |

Git hooks

By default n-gage will automatically configure some git hooks to be run by Husky. If you want to disable this behaviour, add the following line to the very top of your Makefile:

DISABLE_GITHOOKS=true

CLI

This tool helps you to obtain configuration for your project.

$ ngage get-config

get environment variables from Vault

Options:
  --version     Show version number                            [boolean]
  --help        Show help                                      [boolean]
  --app                                     [default: "ft-next-article"]
  --env                           [choices: "dev", "prod", "ci", "test"]
  --custom-env
  --filename                                           [default: ".env"]
  --format               [choices: "simple", "json"] [default: "simple"]
  --team                                               [default: "next"]

For example, to fetch the ci environment variables:

$ ngage get-config --env ci --filename .env-ci --format json
# {
#   "AWS_ACCESS_KEY_ID": "...",
#   "AWS_SECRET_ACCESS_KEY": "...",
# 	...
# }

There is an additional --team flag that lets you specify a team if not next (must match Vault path).

$ ngage get-config --team myteam

FT User Sessions

To get FTSession and FTSession_s environment variables to be populated with up-to-date session tokens from test users, add the following environment variables to your development and/or continuous-integration configs in the Vault:
| Variable | Description | |---|---| | TEST_SESSIONS_URL | url to next-test-sessions-lambda | | TEST_SESSIONS_API_KEY | apikey for the lambda | | TEST_USER_TYPES | user types to get the tokens for (options: premium, standard, expired) |
As a result of this, {USER_TYPE}_FTSession and {USER_TYPE}_FTSession_s environment variables will be populated in the .env file.
Multiple user types can be specified in the TESTUSERTYPES variable.
Example
If you set TEST_USER_TYPES environment variable to premium,standard, these variables will be populated in the .env file: PREMIUM_FTSession, PREMIUM_FTSession_s, STANDARD_FTSession, STANDARD_FTSession_s

Pa11y environment variables

Pa11y configuration has been moved to n-config-pa11y. You can follow the instructions there on how to setup Pa11y. Alternativelly, n-gage will keep this original setup until migration is complete.
| Variable | Description | |---|---| | PA11Y_WAIT | The time to wait before running tests in milliseconds | | PA11Y_ROUTE_EXCEPTIONS | apikey for the lambda | | PA11Y_ROUTE_HEADERS | user types to get the tokens for (options: premium, standard, expired) | | PA11Y_HIDE | A CSS selector to hide elements from testing, selectors can be comma separated | | PA11Y_VIEWPORTS | Set viewports for puppeteer (w1024h768,w375h667) |

Deployment variables

These variables should be declared in the Makefile to set up deployment tasks using Heroku pipelines.
| Variable | Description | |---|---| | VAULT_NAME | Required The name of the app in vault. Should also be the name in package.json eg, ft-next-search-page | | HEROKU_APP_STAGING | Required The name of the Heroku staging app eg, ft-next-search-page-staging | | HEROKU_APP_EU | Required The main Heroku app or the EU Heroku app if it is a multi-region app eg, ft-next-search-page-eu for multi region or ft-next-video-page for single region | | HEROKU_APP_US | Optional The US Heroku app. Only needed if it is a multi region app | | HEROKU_APP_CANARY | Optional The canary Heroku app. Only needed if there is a canary app eg, ft-next-preflight-canary-eu | | HEROKU_APP_CANARY_SCALE | Optional Canary apps only. Specify the number of web dynos for the canary app. If not specified, it will use the HEROKU_APP_EU scale configuration | | REVIEW_APP_CONFIGURE_OVERRIDES | Optional Override environment variables for the review apps. By default it is NODE_ENV=branch, so to add new ones add REVIEW_APP_CONFIGURE_OVERRIDES="NODE_ENV=branch,OTHER_VAR=something" |