base

packages/backend/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

packages/backend/Dockerfile

@@ -0,0 +1,34 @@
+# This dockerfile builds an image for the backend package.
+# It should be executed with the root of the repo as docker context.
+#
+# Before building this image, be sure to have run the following commands in the repo root:
+#
+# yarn install
+# yarn tsc
+# yarn build
+#
+# Once the commands have been run, you can build the image using `yarn build-image`
+
+FROM node:16-bullseye-slim
+
+WORKDIR /app
+
+# install sqlite3 dependencies, you can skip this if you don't use sqlite3 in the image
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential && \
+    rm -rf /var/lib/apt/lists/* && \
+    yarn config set python /usr/bin/python3
+
+# Copy repo skeleton first, to avoid unnecessary docker cache invalidation.
+# The skeleton contains the package.json of each package in the monorepo,
+# and along with yarn.lock and the root package.json, that's enough to run yarn install.
+COPY yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./
+RUN tar xzf skeleton.tar.gz && rm skeleton.tar.gz
+
+RUN yarn install --frozen-lockfile --production --network-timeout 300000 && rm -rf "$(yarn cache dir)"
+
+# Then copy the rest of the backend bundle, along with any other files we might want.
+COPY packages/backend/dist/bundle.tar.gz app-config*.yaml ./
+RUN tar xzf bundle.tar.gz && rm bundle.tar.gz
+
+CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.production.yaml"]

packages/backend/README.md

@@ -0,0 +1,66 @@
+# example-backend
+
+This package is an EXAMPLE of a Backstage backend.
+
+The main purpose of this package is to provide a test bed for Backstage plugins
+that have a backend part. Feel free to experiment locally or within your fork by
+adding dependencies and routes to this backend, to try things out.
+
+Our goal is to eventually amend the create-app flow of the CLI, such that a
+production ready version of a backend skeleton is made alongside the frontend
+app. Until then, feel free to experiment here!
+
+## Development
+
+To run the example backend, first go to the project root and run
+
+```bash
+yarn install
+yarn tsc
+yarn build
+```
+
+You should only need to do this once.
+
+After that, go to the `packages/backend` directory and run
+
+```bash
+AUTH_GOOGLE_CLIENT_ID=x AUTH_GOOGLE_CLIENT_SECRET=x \
+AUTH_GITHUB_CLIENT_ID=x AUTH_GITHUB_CLIENT_SECRET=x \
+AUTH_OAUTH2_CLIENT_ID=x AUTH_OAUTH2_CLIENT_SECRET=x \
+AUTH_OAUTH2_AUTH_URL=x AUTH_OAUTH2_TOKEN_URL=x \
+LOG_LEVEL=debug \
+yarn start
+```
+
+Substitute `x` for actual values, or leave them as dummy values just to try out
+the backend without using the auth or sentry features.
+
+The backend starts up on port 7007 per default.
+
+## Populating The Catalog
+
+If you want to use the catalog functionality, you need to add so called
+locations to the backend. These are places where the backend can find some
+entity descriptor data to consume and serve. For more information, see
+[Software Catalog Overview - Adding Components to the Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview#adding-components-to-the-catalog).
+
+To get started quickly, this template already includes some statically configured example locations
+in `app-config.yaml` under `catalog.locations`. You can remove and replace these locations as you
+like, and also override them for local development in `app-config.local.yaml`.
+
+## Authentication
+
+We chose [Passport](http://www.passportjs.org/) as authentication platform due
+to its comprehensive set of supported authentication
+[strategies](http://www.passportjs.org/packages/).
+
+Read more about the
+[auth-backend](https://github.com/backstage/backstage/blob/master/plugins/auth-backend/README.md)
+and
+[how to add a new provider](https://github.com/backstage/backstage/blob/master/docs/auth/add-auth-provider.md)
+
+## Documentation
+
+- [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
+- [Backstage Documentation](https://github.com/backstage/backstage/blob/master/docs/README.md)

packages/backend/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "backend",
+  "version": "0.0.0",
+  "main": "dist/index.cjs.js",
+  "types": "src/index.ts",
+  "private": true,
+  "backstage": {
+    "role": "backend"
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "build-image": "docker build ../.. -f Dockerfile --tag backstage"
+  },
+  "dependencies": {
+    "app": "link:../app",
+    "@backstage/backend-common": "^0.14.0",
+    "@backstage/backend-tasks": "^0.3.2",
+    "@backstage/catalog-model": "^1.0.3",
+    "@backstage/catalog-client": "^1.0.3",
+    "@backstage/config": "^1.0.1",
+    "@backstage/plugin-app-backend": "^0.3.33",
+    "@backstage/plugin-auth-backend": "^0.14.1",
+    "@backstage/plugin-catalog-backend": "^1.2.0",
+    "@backstage/plugin-permission-common": "^0.6.2",
+    "@backstage/plugin-permission-node": "^0.6.2",
+    "@backstage/plugin-proxy-backend": "^0.2.27",
+    "@backstage/plugin-scaffolder-backend": "^1.3.0",
+    "@backstage/plugin-search-backend": "^0.5.3",
+    "@backstage/plugin-search-backend-module-pg": "^0.3.4",
+    "@backstage/plugin-search-backend-node": "^0.6.2",
+    "@backstage/plugin-techdocs-backend": "^1.1.2",
+    "dockerode": "^3.3.1",
+    "express": "^4.17.1",
+    "express-promise-router": "^4.1.0",
+    "pg": "^8.3.0",
+    "winston": "^3.2.1"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.17.2",
+    "@types/dockerode": "^3.3.0",
+    "@types/express-serve-static-core": "^4.17.5",
+    "@types/express": "^4.17.6",
+    "@types/luxon": "^2.0.4",
+    "better-sqlite3": "^7.5.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

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;
+};