⚠️ 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.
.nvmrc
(run command nvm use
to switch your local Node version to the one in this file).git clone git@github.com:Financial-Times/n-gage.git
cd n-gage
make install
In order to run the tests locally you'll need to run:
make test
npm install --save-dev --no-package-lock @financial-times/n-gage
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
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 TEST_URL environment variable |
verify | Check files for linting errors |
watch | Watch for static asset changes |
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
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
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 |
api_key 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 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 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 |
api_key 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 ) |
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" |