Skip to content

Latest commit

 

History

History
191 lines (121 loc) · 6.43 KB

README.md

File metadata and controls

191 lines (121 loc) · 6.43 KB
Raw

Octopus API

The Octopus API is a Prisma project, using PostgreSQL.

Prerequisites

Environment File

Create a .env file inside ~/api using cp .env.example .env.

Make sure to update the values within to match your environment.

Changes to .env file

When adding a new item to the .env file, make sure to update the environment variables in the docker-compose.yml file so the API tests can access them.

AWS/Serverless credentials setup

You will need AWS credentials to run the app locally with serverless-offline. These should be exported as local environment variables, like this:

export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."

You will also need to tell the system your serverless license key. This can be done by running (from the api directory) npx sls login and following the wizard.

Alternatively you can just set it as an environment variable:

export SERVERLESS_LICENSE_KEY="..."

Getting started

First, start up Docker Desktop and within the root directory run:

docker compose up

All of the following commands should be ran at the root of this directory (~/api).

Then, open another terminal and within the API directory run:

~/api$ npm i

Then you can seed the database and start the API:

$ ~/api$ npm run seed:local
$ ~/api$ npm run dev

To run all tests locally (the API must be running first):

~/api$ npm run test:local

To view the UI, you will also need to start the UI Next.js application. More information can be found in the UI readme.

Prisma

Commands

Whenever a change is made to the Prisma Schema you must run npx prisma generate in order for the Prisma Client to update.
If you do not run this, the application code will break as the client will not reflect the latest schema.

~/api$ npx prisma generate

Migrate and reseed the database:

~/api$ npm run seed:local

Create a new migration:

~/api$ npx prisma migrate dev --name new_migration_name

You can then apply the changes made by the new migration using the two commands above (generate and migrate reset).

More information on migrations in Prisma can be found here: Prisma Migrate Documentation.

Seed data

There are three sets of seed data, laid out as follows:

prisma/seeds
│
└───local
│   │
│   └───dev
|   |
|   └───unitTesting
│
└───prod

This is because they have different use cases.

  • local (dev):
    • A wide set of data useful for local development. For example, the requisite data for testing out integrations - to import data from the ARI database, certain topic mappings and departmental user accounts are expected to exist.
    • Seeded using the command npm run seed:local.
  • local (unitTesting):
    • A minimal set of data providing only what is needed for the jest tests to run. This needs to be small because the database is reseeded again and again while the test suite is run, so that process needs to be as quick as possible.
    • Seeded using the testSeed() function from src/lib/testUtils.
  • prod:
    • Used for seeding a fresh prod instance.
    • Seeded by running STAGE=prod npx prisma migrate reset --force (though it's unlikely you'll ever need to do this).

Opensearch

This provides a search index for publications. Locally, it runs in a docker container, and on AWS it runs as a dedicated service. Other searchable models such as authors and topics aren't stored in opensearch - their search functions use prisma.

The field mapping of the index is not explicitly defined; it is set automatically when a document is inserted into it.

Reindexing

There is a script which deletes and recreates the publications index, inserting a document into it for each live publication. This can be run from the api directory with npm run reindex.

A similar process happens when the database is seeded. After publications are inserted into the database, they are also fed into a blank opensearch index.

Integrations

Octopus is built to integrate with some external systems in order to import publications. For more information please read the dedicated integrations readme.

Technologies

Languages

ORM

Search

Libraries

Linting

Testing

API tests are written in Jest and each endpoint has tests written to ensure the code is correct and working. These can be run manually using npm run test:local.

Overridden dependencies

This is a place to track where we have added dependency overrides in package.json and explain why so that we can understand when they're no longer necessary.