Generates JSDoc and SassDoc json for Origami components.
Running Origami Codedocs requires [Node.js] 14.x and [npm].
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/
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.
Configuration for Fastly is required in CI:
The following environment variables are also required in CI for a production deploy:
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.
Routes available include the following:
Routes for jsdoc:
/jsdoc/{componentId}
Routes for sassdoc:
/sassdoc/{componentId}
Routes for health:
/__health
/__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]"
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
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
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.
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.
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.
This software is published by the Financial Times under the MIT licence.