Expose new option in techdocs cli generate command

The re-assignment of container user on macOS/Linux is troublesome when running on rootless GitHub runners; adding a way to bypass this for generation.

This should be a non-breaking change and just adds functionality.

Signed-off-by: Kamil Zainal <gh@akza.dev>

.changeset/spotty-olives-share.md

@@ -0,0 +1,7 @@
+---
+'@techdocs/cli': minor
+'@backstage/plugin-techdocs-node': minor
+'@backstage/backend-common': patch
+---
+
+Add command `--runAsDefaultUser` for `@techdocs/cli generate` to bypass running the docker builds as host user for macOS and Linux.

packages/backend-common/src/util/ContainerRunner.ts

@@ -30,6 +30,7 @@ export type RunContainerOptions = {
   workingDir?: string;
   envVars?: Record<string, string>;
   pullImage?: boolean;
+  defaultUser?: boolean;
 };
 
 /**

packages/backend-common/src/util/DockerContainerRunner.ts

@@ -46,6 +46,7 @@ export class DockerContainerRunner implements ContainerRunner {
       workingDir,
       envVars = {},
       pullImage = true,
+      defaultUser = false
     } = options;
 
     // Show a better error message when Docker is unavailable.
@@ -71,7 +72,7 @@ export class DockerContainerRunner implements ContainerRunner {
     }
 
     const userOptions: UserOptions = {};
-    if (process.getuid && process.getgid) {
+    if (!defaultUser && (process.getuid && process.getgid)) {
       // Files that are created inside the Docker container will be owned by
       // root on the host system on non Mac systems, because of reasons. Mainly the fact that
       // volume sharing is done using NFS on Mac and actual mounts in Linux world.

packages/techdocs-cli/src/commands/generate/generate.ts

@@ -114,6 +114,7 @@ export default async function generate(opts: OptionValues) {
     etag: opts.etag,
     logStream: getLogStream(logger),
     siteOptions: { name: opts.siteName },
+    runAsDefaultUser: opts.runAsDefaultUser
   });
 
   if (configIsTemporary) {

packages/techdocs-cli/src/commands/index.ts

@@ -75,6 +75,11 @@ export function registerCommands(program: Command) {
       'Plugins which should be added automatically to the mkdocs.yaml file',
       [],
     )
+    .option(
+      '--runAsDefaultUser',
+      'Bypass setting the container user as the same user and group id as host for Linux and MacOS',
+      false
+    )
     .alias('build')
     .action(lazy(() => import('./generate/generate').then(m => m.default)));
 

plugins/techdocs-node/src/stages/generate/techdocs.ts

@@ -97,6 +97,7 @@ export class TechdocsGenerator implements GeneratorBase {
       logger: childLogger,
       logStream,
       siteOptions,
+      runAsDefaultUser
     } = options;
 
     // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url
@@ -171,6 +172,7 @@ export class TechdocsGenerator implements GeneratorBase {
             // write to, otherwise they will just fail trying to write to /
             envVars: { HOME: '/tmp' },
             pullImage: this.options.pullImage,
+            defaultUser: runAsDefaultUser
           });
           childLogger.info(
             `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`,

plugins/techdocs-node/src/stages/generate/types.ts

@@ -64,6 +64,7 @@ export type GeneratorRunOptions = {
   logger: Logger;
   logStream?: Writable;
   siteOptions?: { name?: string };
+  runAsDefaultUser?: boolean;
 };
 
 /**