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

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:

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 TEST_USER_TYPES 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.

Deployment variables

These variables should be declared in the Makefile to set up deployment tasks using Heroku pipelines.