zod-openapi-demo

Next steps:

1. Finish templating if this was skipped earlier:

   yarn skuba configure

2. Create a new repository in the appropriate GitHub organisation.

3. Add the repository to BuildAgency; see Builds at SEEK for more information.

4. Add Datadog configuration and data classification tags to .gantry/common.yml; see the Gantry documentation for more information.

5. Push local commits to the upstream GitHub branch.

6. Configure GitHub repository settings.

7. Delete this checklist 😌.

Design

zod-openapi-demo is a Node.js HTTP server built in line with our technology strategy. It uses the Koa middleware framework and common SEEK packages. Resource APIs enable synchronous interactions and serve as the backbone of SEEK's general service architecture.

The koa-rest-api template is modelled after a hypothetical service for posting and retrieving job advertisements. It's stubbed out with in-memory storage which can observed by standing up an environment with multiple instances. Storage is local to each instance, so load balancing across the instances may render a read inconsistent with a previous write. This would be replaced with an external data store in production.

This project is deployed as a containerised application with Gantry. A typical resource API instance does not require more than 1 vCPU, so we eschew clustering configurations in favour of a single Node.js process per container. Under load, we autoscale horizontally in terms of container count up to autoScaling.maxCount.

Gantry configures CodeDeploy for a blue-green deployment approach. A smoke test is run against the new version before traffic is switched over, providing an opportunity to test access and connectivity to online dependencies. This defaults to an HTTP request to the GET /smoke endpoint.

Development

Test

yarn test

Lint

# Fix issues
yarn format

# Check for issues
yarn lint

Start

# Start a local HTTP server
yarn start

# Start with Node.js Inspector enabled
yarn start:debug

Deploy

This project is deployed through a Buildkite pipeline.

• Commits to a feature branch can be deployed to the dev environment by unblocking a step in the Buildkite UI
• Commits to the default branch are automatically deployed to the dev and prod environments in sequence

To rapidly roll back a change, retry an individual deployment step from the previous build in Buildkite. Note that this will introduce drift between the head of the default Git branch and the live environment; use with caution and always follow up with a proper revert or fix in Git history.

Support

Dev

TODO: add support links for the dev environment.

Prod

TODO: add support links for the prod environment.