README.md

ADR Backend

This ADR backend plugin is primarily responsible for the following:

• Provides a DefaultAdrCollatorFactory, which can be used in the search backend to index ADR documents associated with entities to your Backstage Search.

• Provides endpoints that use UrlReaders for getting ADR documents (used in the ADR frontend plugin).

Install

Setup your integrations config

First off you'll need to setup your integrations config inside your app-config.yaml. You can skip this step if it's already setup previously, and if you need help configuring this you can read the integrations documentation

Up and Running

Here's how to get the backend up and running:

1. First we need to add the @backstage-community/plugin-adr-backend package to your backend:

# From your Backstage root directory
yarn --cwd packages/backend add @backstage-community/plugin-adr-backend

2. Then we will create a new file named packages/backend/src/plugins/adr.ts, and add the following to it:

import { createRouter } from '@backstage-community/plugin-adr-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  return await createRouter({
    reader: env.reader,
    cacheClient: env.cache.getClient(),
    logger: env.logger,
  });
}

3. Next we wire this into the overall backend router, edit packages/backend/src/index.ts:

import adr from './plugins/adr';
// ...
async function main() {
  // ...
  // Add this line under the other lines that follow the useHotMemoize pattern
  const adrEnv = useHotMemoize(module, () => createEnv('adr'));
  // ...
  // Insert this line under the other lines that add their routers to apiRouter in the same way
  apiRouter.use('/adr', await adr(adrEnv));

4. Now run yarn start-backend from the repo root

New Backend System

The ADR backend plugin has support for the new backend system, here's how you can set that up:

In your packages/backend/src/index.ts make the following changes:

  const backend = createBackend();

+ backend.add(import('@backstage-community/plugin-adr-backend'));

// ... other feature additions

  backend.start();

Indexing ADR documents for search

Before you are able to start indexing ADR documents to search, you need to go through the search getting started guide.

When you have your packages/backend/src/plugins/search.ts file ready to make modifications, install this plugin and add the following code snippet to add the DefaultAdrCollatorFactory. Also make sure to set up the frontend ADR plugin so search results can be routed correctly.

# From your Backstage root directory
yarn --cwd packages/backend add @backstage-community/plugin-adr-backend

import { DefaultAdrCollatorFactory } from '@backstage-community/plugin-adr-backend';

...

indexBuilder.addCollator({
  schedule,
  factory: DefaultAdrCollatorFactory.fromConfig({
    cache: env.cache,
    config: env.config,
    discovery: env.discovery,
    logger: env.logger,
    reader: env.reader,
    tokenManager: env.tokenManager,
  }),
});

Parsing custom ADR document formats

By default, the DefaultAdrCollatorFactory will parse and index documents that follow MADR v3.0.0 and MADR v2.x standard file name and template format. If you use a different ADR format and file name convention, you can configure DefaultAdrCollatorFactory with custom adrFilePathFilterFn and parser options (see type definitions for details):

DefaultAdrCollatorFactory.fromConfig({
  ...
  parser: myCustomAdrParser,
  adrFilePathFilterFn: myCustomAdrFilePathFilter,
  ...
})