Merge pull request #20738 from akz08/add-docker-useroptions-bypass

Add a way to bypass user modification for TechDocs CLI docs generation in Docker

.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.

docs/features/techdocs/cli.md

@@ -147,6 +147,7 @@ Options:
                                   Defaults to false, which means that the techdocs-core plugin is always added to the mkdocs file.
   --legacyCopyReadmeMdToIndexMd   Attempt to ensure an index.md exists falling back to using <docs-dir>/README.md or README.md
                                   in case a default <docs-dir>/index.md is not provided. (default: false)
+  --runAsDefaultUser              Bypass setting the container user as the same user and group id as host for Linux and MacOS (default: false)
   -v --verbose                    Enable verbose output. (default: false)
   -h, --help                      display help for command
 ```

packages/backend-common/api-report.md

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

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/cli-report.md

@@ -38,6 +38,7 @@ Options:
   --omitTechdocsCoreMkdocsPlugin
   --legacyCopyReadmeMdToIndexMd
   --defaultPlugin [defaultPlugins...]
+  --runAsDefaultUser
   -h, --help
 ```
 

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/api-report.md

@@ -62,6 +62,7 @@ export type GeneratorRunOptions = {
   siteOptions?: {
     name?: string;
   };
+  runAsDefaultUser?: boolean;
 };
 
 // @public

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;
 };
 
 /**