# origami-codedocs

**Repository Path**: mirrors_Financial-Times/origami-codedocs

## Basic Information

- **Project Name**: origami-codedocs
- **Description**: A service to generate JSDoc and SassDoc json for Origami components.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-24
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Origami CodeDocs [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](#licence)

Generates JSDoc and SassDoc json for Origami components.

## Table Of Contents

- [Origami CodeDocs ](#origami-codedocs-)
  - [Table Of Contents](#table-of-contents)
  - [Requirements](#requirements)
  - [Running Locally](#running-locally)
  - [Configuration](#configuration)
    - [Required everywhere](#required-everywhere)
    - [Required in CI](#required-in-ci)
  - [Operational Documentation](#operational-documentation)
  - [Testing](#testing)
  - [Deployment](#deployment)
  - [Monitoring](#monitoring)
  - [Trouble-Shooting](#trouble-shooting)
    - [Upating Fastly failed during a production deploy?](#upating-fastly-failed-during-a-production-deploy)
    - [Integration tests are failing due to forbidden requests.](#integration-tests-are-failing-due-to-forbidden-requests)
    - [Forbidden requests.](#forbidden-requests)
  - [Licence](#licence)

## 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:

```sh
npm install
```

Run the application in development mode with:

```sh
npx serverless offline start
```

Now we can access the app over HTTP on port `3000`: [http://localhost:3000/](http://localhost:3000/)

## Configuration

We configure Origami CodeDocs using environment variables. In development, configurations are set from [Doppler CLI](https://docs.doppler.com/docs/install-cli) (You might need to request contributor access). Login in Doppler and run the following command to setup Doppler within the repo:

```sh
doppler setup
```

Setup will ask you to select the project you want to use, select `origami-codedocs` and then select the `local` environment. Once setup is complete you can download the secrets to your local environment by running:

```sh
doppler secrets download --format --no-file > .env
```

### Required everywhere

- AWS_ACCOUNT_ID
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- NODE_ENV
- SENTRY_DSN
- CODEDOCS_API_KEY_NAME
- CODEDOCS_API_KEY

In production, these are set during deployment through CI config.

### 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:

```sh
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.

```sh
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:

```sh
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:

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

## Monitoring

- [Sentry dashboard (Prod)][sentry-prod]: records application errors in the production app
- [Sentry dashboard (Dev)][sentry-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](#operational-documentation). 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](#operational-documentation). The api key of a deployed application can be found under "apigateway" in AWS.

[sentry-prod]: https://sentry.io/nextftcom/origami-codedocs-prod/
[sentry-dev]: https://sentry.io/nextftcom/origami-codedocs/

## Licence

This software is published by the Financial Times under the [MIT licence](http://opensource.org/licenses/MIT).