base

packages/backend/src/index.test.ts

@@ -0,0 +1,8 @@
+import { PluginEnvironment } from './types';
+
+describe('test', () => {
+  it('unbreaks the test runner', () => {
+    const unbreaker = {} as PluginEnvironment;
+    expect(unbreaker).toBeTruthy();
+  });
+});

packages/backend/src/index.ts

@@ -0,0 +1,109 @@
+/*
+ * Hi!
+ *
+ * Note that this is an EXAMPLE Backstage backend. Please check the README.
+ *
+ * Happy hacking!
+ */
+
+import Router from 'express-promise-router';
+import {
+  createServiceBuilder,
+  loadBackendConfig,
+  getRootLogger,
+  useHotMemoize,
+  notFoundHandler,
+  CacheManager,
+  DatabaseManager,
+  SingleHostDiscovery,
+  UrlReaders,
+  ServerTokenManager,
+} from '@backstage/backend-common';
+import { TaskScheduler } from '@backstage/backend-tasks';
+import { Config } from '@backstage/config';
+import app from './plugins/app';
+import auth from './plugins/auth';
+import catalog from './plugins/catalog';
+import scaffolder from './plugins/scaffolder';
+import proxy from './plugins/proxy';
+import techdocs from './plugins/techdocs';
+import search from './plugins/search';
+import { PluginEnvironment } from './types';
+import { ServerPermissionClient } from '@backstage/plugin-permission-node';
+
+function makeCreateEnv(config: Config) {
+  const root = getRootLogger();
+  const reader = UrlReaders.default({ logger: root, config });
+  const discovery = SingleHostDiscovery.fromConfig(config);
+  const cacheManager = CacheManager.fromConfig(config);
+  const databaseManager = DatabaseManager.fromConfig(config);
+  const tokenManager = ServerTokenManager.noop();
+  const taskScheduler = TaskScheduler.fromConfig(config);
+  const permissions = ServerPermissionClient.fromConfig(config, {
+    discovery,
+    tokenManager,
+  });
+
+  root.info(`Created UrlReader ${reader}`);
+
+  return (plugin: string): PluginEnvironment => {
+    const logger = root.child({ type: 'plugin', plugin });
+    const database = databaseManager.forPlugin(plugin);
+    const cache = cacheManager.forPlugin(plugin);
+    const scheduler = taskScheduler.forPlugin(plugin);
+    return {
+      logger,
+      database,
+      cache,
+      config,
+      reader,
+      discovery,
+      tokenManager,
+      scheduler,
+      permissions,
+    };
+  };
+}
+
+async function main() {
+  const config = await loadBackendConfig({
+    argv: process.argv,
+    logger: getRootLogger(),
+  });
+  const createEnv = makeCreateEnv(config);
+
+  const catalogEnv = useHotMemoize(module, () => createEnv('catalog'));
+  const scaffolderEnv = useHotMemoize(module, () => createEnv('scaffolder'));
+  const authEnv = useHotMemoize(module, () => createEnv('auth'));
+  const proxyEnv = useHotMemoize(module, () => createEnv('proxy'));
+  const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs'));
+  const searchEnv = useHotMemoize(module, () => createEnv('search'));
+  const appEnv = useHotMemoize(module, () => createEnv('app'));
+
+  const apiRouter = Router();
+  apiRouter.use('/catalog', await catalog(catalogEnv));
+  apiRouter.use('/scaffolder', await scaffolder(scaffolderEnv));
+  apiRouter.use('/auth', await auth(authEnv));
+  apiRouter.use('/techdocs', await techdocs(techdocsEnv));
+  apiRouter.use('/proxy', await proxy(proxyEnv));
+  apiRouter.use('/search', await search(searchEnv));
+
+  // Add backends ABOVE this line; this 404 handler is the catch-all fallback
+  apiRouter.use(notFoundHandler());
+
+  const service = createServiceBuilder(module)
+    .loadConfig(config)
+    .addRouter('/api', apiRouter)
+    .addRouter('', await app(appEnv));
+
+  await service.start().catch(err => {
+    console.log(err);
+    process.exit(1);
+  });
+}
+
+module.hot?.accept();
+main().catch(error => {
+  console.error(`Backend failed to start up, ${error}`);
+  process.exit(1);
+});

packages/backend/src/plugins/app.ts

@@ -0,0 +1,14 @@
+import { createRouter } from '@backstage/plugin-app-backend';
+import { Router } from 'express';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  return await createRouter({
+    logger: env.logger,
+    config: env.config,
+    database: env.database,
+    appPackageName: 'app',
+  });
+}

packages/backend/src/plugins/auth.ts

@@ -0,0 +1,54 @@
+import {
+  createRouter,
+  providers,
+  defaultAuthProviderFactories,
+} from '@backstage/plugin-auth-backend';
+import { Router } from 'express';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  return await createRouter({
+    logger: env.logger,
+    config: env.config,
+    database: env.database,
+    discovery: env.discovery,
+    tokenManager: env.tokenManager,
+    providerFactories: {
+      ...defaultAuthProviderFactories,
+
+      // This replaces the default GitHub auth provider with a customized one.
+      // The `signIn` option enables sign-in for this provider, using the
+      // identity resolution logic that's provided in the `resolver` callback.
+      //
+      // This particular resolver makes all users share a single "guest" identity.
+      // It should only be used for testing and trying out Backstage.
+      //
+      // If you want to use a production ready resolver you can switch to the
+      // the one that is commented out below, it looks up a user entity in the
+      // catalog using the GitHub username of the authenticated user.
+      // That resolver requires you to have user entities populated in the catalog,
+      // for example using https://backstage.io/docs/integrations/github/org
+      //
+      // There are other resolvers to choose from, and you can also create
+      // your own, see the auth documentation for more details:
+      //
+      //   https://backstage.io/docs/auth/identity-resolver
+      github: providers.github.create({
+        signIn: {
+          resolver(_, ctx) {
+            const userRef = 'user:default/guest'; // Must be a full entity reference
+            return ctx.issueToken({
+              claims: {
+                sub: userRef, // The user's own identity
+                ent: [userRef], // A list of identities that the user claims ownership through
+              },
+            });
+          },
+          // resolver: providers.github.resolvers.usernameMatchingUserEntityName(),
+        },
+      }),
+    },
+  });
+}

packages/backend/src/plugins/catalog.ts

@@ -0,0 +1,14 @@
+import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
+import { ScaffolderEntitiesProcessor } from '@backstage/plugin-scaffolder-backend';
+import { Router } from 'express';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  const builder = await CatalogBuilder.create(env);
+  builder.addProcessor(new ScaffolderEntitiesProcessor());
+  const { processingEngine, router } = await builder.build();
+  await processingEngine.start();
+  return router;
+}

packages/backend/src/plugins/proxy.ts

@@ -0,0 +1,13 @@
+import { createRouter } from '@backstage/plugin-proxy-backend';
+import { Router } from 'express';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  return await createRouter({
+    logger: env.logger,
+    config: env.config,
+    discovery: env.discovery,
+  });
+}

packages/backend/src/plugins/scaffolder.ts

@@ -0,0 +1,20 @@
+import { CatalogClient } from '@backstage/catalog-client';
+import { createRouter } from '@backstage/plugin-scaffolder-backend';
+import { Router } from 'express';
+import type { PluginEnvironment } from '../types';
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  const catalogClient = new CatalogClient({
+    discoveryApi: env.discovery,
+  });
+
+  return await createRouter({
+    logger: env.logger,
+    config: env.config,
+    database: env.database,
+    reader: env.reader,
+    catalogClient,
+  });
+}

packages/backend/src/plugins/search.ts

@@ -0,0 +1,66 @@
+import { useHotCleanup } from '@backstage/backend-common';
+import { createRouter } from '@backstage/plugin-search-backend';
+import {
+  IndexBuilder,
+  LunrSearchEngine,
+} from '@backstage/plugin-search-backend-node';
+import { PluginEnvironment } from '../types';
+import { DefaultCatalogCollatorFactory } from '@backstage/plugin-catalog-backend';
+import { DefaultTechDocsCollatorFactory } from '@backstage/plugin-techdocs-backend';
+import { Router } from 'express';
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  // Initialize a connection to a search engine.
+  const searchEngine = new LunrSearchEngine({
+    logger: env.logger,
+  });
+  const indexBuilder = new IndexBuilder({
+    logger: env.logger,
+    searchEngine,
+  });
+
+  const schedule = env.scheduler.createScheduledTaskRunner({
+    frequency: { minutes: 10 },
+    timeout: { minutes: 15 },
+    // A 3 second delay gives the backend server a chance to initialize before
+    // any collators are executed, which may attempt requests against the API.
+    initialDelay: { seconds: 3 },
+  });
+
+  // Collators are responsible for gathering documents known to plugins. This
+  // collator gathers entities from the software catalog.
+  indexBuilder.addCollator({
+    schedule,
+    factory: DefaultCatalogCollatorFactory.fromConfig(env.config, {
+      discovery: env.discovery,
+      tokenManager: env.tokenManager,
+    }),
+  });
+
+  // collator gathers entities from techdocs.
+  indexBuilder.addCollator({
+    schedule,
+    factory: DefaultTechDocsCollatorFactory.fromConfig(env.config, {
+      discovery: env.discovery,
+      logger: env.logger,
+      tokenManager: env.tokenManager,
+    }),
+  });
+
+  // The scheduler controls when documents are gathered from collators and sent
+  // to the search engine for indexing.
+  const { scheduler } = await indexBuilder.build();
+  scheduler.start();
+
+  useHotCleanup(module, () => scheduler.stop());
+
+  return await createRouter({
+    engine: indexBuilder.getSearchEngine(),
+    types: indexBuilder.getDocumentTypes(),
+    permissions: env.permissions,
+    config: env.config,
+    logger: env.logger,
+  });
+}

packages/backend/src/plugins/techdocs.ts

@@ -0,0 +1,51 @@
+import { DockerContainerRunner } from '@backstage/backend-common';
+import {
+  createRouter,
+  Generators,
+  Preparers,
+  Publisher,
+} from '@backstage/plugin-techdocs-backend';
+import Docker from 'dockerode';
+import { Router } from 'express';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  // Preparers are responsible for fetching source files for documentation.
+  const preparers = await Preparers.fromConfig(env.config, {
+    logger: env.logger,
+    reader: env.reader,
+  });
+
+  // Docker client (conditionally) used by the generators, based on techdocs.generators config.
+  const dockerClient = new Docker();
+  const containerRunner = new DockerContainerRunner({ dockerClient });
+
+  // Generators are used for generating documentation sites.
+  const generators = await Generators.fromConfig(env.config, {
+    logger: env.logger,
+    containerRunner,
+  });
+
+  // Publisher is used for
+  // 1. Publishing generated files to storage
+  // 2. Fetching files from storage and passing them to TechDocs frontend.
+  const publisher = await Publisher.fromConfig(env.config, {
+    logger: env.logger,
+    discovery: env.discovery,
+  });
+
+  // checks if the publisher is working and logs the result
+  await publisher.getReadiness();
+
+  return await createRouter({
+    preparers,
+    generators,
+    publisher,
+    logger: env.logger,
+    config: env.config,
+    discovery: env.discovery,
+    cache: env.cache,
+  });
+}

packages/backend/src/types.ts

@@ -0,0 +1,23 @@
+import { Logger } from 'winston';
+import { Config } from '@backstage/config';
+import {
+  PluginCacheManager,
+  PluginDatabaseManager,
+  PluginEndpointDiscovery,
+  TokenManager,
+  UrlReader,
+} from '@backstage/backend-common';
+import { PluginTaskScheduler } from '@backstage/backend-tasks';
+import { PermissionEvaluator } from '@backstage/plugin-permission-common';
+
+export type PluginEnvironment = {
+  logger: Logger;
+  database: PluginDatabaseManager;
+  cache: PluginCacheManager;
+  config: Config;
+  reader: UrlReader;
+  discovery: PluginEndpointDiscovery;
+  tokenManager: TokenManager;
+  scheduler: PluginTaskScheduler;
+  permissions: PermissionEvaluator;
+};