Readme: origami-codedocs

Generates JSDoc and SassDoc json for Origami components.

Table Of Contents

Requirements

Running Origami Codedocs requires [Node.js] 14.x and [npm].

Running Locally

Before we can run the application, we'll need to install dependencies:

npm install

Run the application in development mode with:

npx serverless offline start

Now we can access the app over HTTP on port 3000: http://localhost:3000/

Configuration

We configure Origami CodeDocs using environment variables. In development, configurations are set in a .env file. In production, these are set during deployment through CI config.

Required everywhere

• AWS_ACCOUNT_ID
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• NODE_ENV
• SENTRY_DSN
• CODEDOCS_API_KEY_NAME
• CODEDOCS_API_KEY

Required in CI

Configuration for Fastly is required in CI:

• FASTLY_PROD
• FASTLY_SERVICE_PROD
• FASTLY_BACKEND_NAME_PROD

The following environment variables are also required in CI for a production deploy:

• AWS_ACCOUNT_ID_PROD
• AWS_ACCESS_KEY_ID_PROD
• AWS_SECRET_ACCESS_KEY_PROD

These production environment variables are mapped during a production deploy e.g. AWS_ACCOUNT_ID is automatically set to the value of AWS_ACCOUNT_ID_PROD. We do this as, at the time of writing, CI contexts are not available to users without root permissions.

Operational Documentation

Routes available include the following:

Routes for jsdoc:

• GET /jsdoc/{componentId}

Routes for sassdoc:

• GET /sassdoc/{componentId}

Routes for health:

• GET /__health
• GET /__gtg

Where componentId is the name and version of the component e.g. o-grid@v4.4.4.

To get JSDocs or SassDocs we must set the x-api-key header, which is generated by Serverless when starting the application:

Serverless: Starting Offline: dev/eu-west-1.
Serverless: Key with token: [your key here]
Serverless: Remember to use x-api-key on the request headers

In a deployed environment these routes are prefixed with the "stage" either prod or dev. The x-api-key for a deployed service is available in Vault, or the latest may be found in AWS under "apigateway". This is an example request to the production service:

curl https://origami-codedocs.in.ft.com/prod/sassdoc/o-grid@v4.4.4 -H "x-api-key:[key here]"

Testing

The tests are split into unit tests and integration tests. Unit tests are used for business logic, such as parsing a custom @brand SassDoc parameter. Integration tests are used to test a deployed service end-to-end.

npm run test                                                  # run all the tests
npm run test-unit                                             # run the unit tests
INTEGRATION_ENDPOINT=localhost:3000/dev npm run test-integration  # run the integration tests against localhost (the service must be running locally first)

Integration tests run against the endpoint defined by the environment variable INTEGRATION_ENDPOINT. If it is not configured the service endpoint defined in .dev-stack.yml is used by default. This is generated automatically by serverless on deployment.

The code will also need to pass linting on CI, you can run the linter locally with:

npm run lint

Deployment

CI will deploy the service on merge to the master branch. It will first deploy to the development dev environment to run integration tests. If tests pass it then deploys to the production prod environment.

If you would like to deploy to the development dev environment manually, run:

npx serverless deploy --stage dev --region eu-west-1

Monitoring

• Sentry dashboard (Prod): records application errors in the production app
• Sentry dashboard (Dev): records application errors in the development app

Trouble-Shooting

Upating Fastly failed during a production deploy?

This is likely due to the Fastly API key expiring. Create a new personal api key in Fastly with access to the origami-codedocs.in.ft.com service, and add this environment variable to CI.

Integration tests are failing due to forbidden requests.

If the service returns 403 "Forbidden" errors when running integration tests, it is likely the CODEDOCS_API_KEY environment variable is incorrect.

Locally ensure CODEDOCS_API_KEY is set to the api key output by Serverless when running the app. For the dev environment, make sure CODEDOCS_API_KEY is set to the right value in CI. The api key of a deployed application can be found under "apigateway" in AWS.

Forbidden requests.

Ensure the correct x-api-key header is set when making requests. Locally the key is output by Serverless when running the app. The api key of a deployed application can be found under "apigateway" in AWS.

Licence

This software is published by the Financial Times under the MIT licence.