From d15d483a4928fc26942027e590cdd190ce8622e7 Mon Sep 17 00:00:00 2001 From: Kamil Zainal Date: Mon, 23 Oct 2023 14:49:19 +0100 Subject: [PATCH 1/4] 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 --- .changeset/spotty-olives-share.md | 7 +++++++ packages/backend-common/src/util/ContainerRunner.ts | 1 + packages/backend-common/src/util/DockerContainerRunner.ts | 3 ++- packages/techdocs-cli/src/commands/generate/generate.ts | 1 + packages/techdocs-cli/src/commands/index.ts | 5 +++++ plugins/techdocs-node/src/stages/generate/techdocs.ts | 2 ++ plugins/techdocs-node/src/stages/generate/types.ts | 1 + 7 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 .changeset/spotty-olives-share.md diff --git a/.changeset/spotty-olives-share.md b/.changeset/spotty-olives-share.md new file mode 100644 index 0000000000..7437b3af00 --- /dev/null +++ b/.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. diff --git a/packages/backend-common/src/util/ContainerRunner.ts b/packages/backend-common/src/util/ContainerRunner.ts index 22e40ec455..7dc12919b3 100644 --- a/packages/backend-common/src/util/ContainerRunner.ts +++ b/packages/backend-common/src/util/ContainerRunner.ts @@ -30,6 +30,7 @@ export type RunContainerOptions = { workingDir?: string; envVars?: Record; pullImage?: boolean; + defaultUser?: boolean; }; /** diff --git a/packages/backend-common/src/util/DockerContainerRunner.ts b/packages/backend-common/src/util/DockerContainerRunner.ts index 4d4684c814..4058a4dae1 100644 --- a/packages/backend-common/src/util/DockerContainerRunner.ts +++ b/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. diff --git a/packages/techdocs-cli/src/commands/generate/generate.ts b/packages/techdocs-cli/src/commands/generate/generate.ts index 934eaf1efd..24e3d46017 100644 --- a/packages/techdocs-cli/src/commands/generate/generate.ts +++ b/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) { diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index 10a00da513..3ea58c86dd 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/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))); diff --git a/plugins/techdocs-node/src/stages/generate/techdocs.ts b/plugins/techdocs-node/src/stages/generate/techdocs.ts index b1baf214b3..cca8cd06c3 100644 --- a/plugins/techdocs-node/src/stages/generate/techdocs.ts +++ b/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`, diff --git a/plugins/techdocs-node/src/stages/generate/types.ts b/plugins/techdocs-node/src/stages/generate/types.ts index eca1057914..149c3c2195 100644 --- a/plugins/techdocs-node/src/stages/generate/types.ts +++ b/plugins/techdocs-node/src/stages/generate/types.ts @@ -64,6 +64,7 @@ export type GeneratorRunOptions = { logger: Logger; logStream?: Writable; siteOptions?: { name?: string }; + runAsDefaultUser?: boolean; }; /** From 20005cf26d28e365e9f91d958d5004d174233ac5 Mon Sep 17 00:00:00 2001 From: Kamil Zainal Date: Mon, 23 Oct 2023 15:11:08 +0100 Subject: [PATCH 2/4] Update techdocs cli docs Signed-off-by: Kamil Zainal --- docs/features/techdocs/cli.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index 9704b9b21b..cc356f68d1 100644 --- a/docs/features/techdocs/cli.md +++ b/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 /README.md or README.md in case a default /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 ``` From 31fd1146af1626e1479b76199b2e56291818b0e6 Mon Sep 17 00:00:00 2001 From: Kamil Zainal Date: Mon, 23 Oct 2023 15:34:38 +0100 Subject: [PATCH 3/4] Run `prettier:fix` Signed-off-by: Kamil Zainal --- packages/backend-common/src/util/DockerContainerRunner.ts | 4 ++-- packages/techdocs-cli/src/commands/generate/generate.ts | 2 +- packages/techdocs-cli/src/commands/index.ts | 2 +- plugins/techdocs-node/src/stages/generate/techdocs.ts | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/backend-common/src/util/DockerContainerRunner.ts b/packages/backend-common/src/util/DockerContainerRunner.ts index 4058a4dae1..986470eb98 100644 --- a/packages/backend-common/src/util/DockerContainerRunner.ts +++ b/packages/backend-common/src/util/DockerContainerRunner.ts @@ -46,7 +46,7 @@ export class DockerContainerRunner implements ContainerRunner { workingDir, envVars = {}, pullImage = true, - defaultUser = false + defaultUser = false, } = options; // Show a better error message when Docker is unavailable. @@ -72,7 +72,7 @@ export class DockerContainerRunner implements ContainerRunner { } const userOptions: UserOptions = {}; - if (!defaultUser && (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. diff --git a/packages/techdocs-cli/src/commands/generate/generate.ts b/packages/techdocs-cli/src/commands/generate/generate.ts index 24e3d46017..bf6910ff4a 100644 --- a/packages/techdocs-cli/src/commands/generate/generate.ts +++ b/packages/techdocs-cli/src/commands/generate/generate.ts @@ -114,7 +114,7 @@ export default async function generate(opts: OptionValues) { etag: opts.etag, logStream: getLogStream(logger), siteOptions: { name: opts.siteName }, - runAsDefaultUser: opts.runAsDefaultUser + runAsDefaultUser: opts.runAsDefaultUser, }); if (configIsTemporary) { diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index 3ea58c86dd..bb469ec82a 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -78,7 +78,7 @@ export function registerCommands(program: Command) { .option( '--runAsDefaultUser', 'Bypass setting the container user as the same user and group id as host for Linux and MacOS', - false + false, ) .alias('build') .action(lazy(() => import('./generate/generate').then(m => m.default))); diff --git a/plugins/techdocs-node/src/stages/generate/techdocs.ts b/plugins/techdocs-node/src/stages/generate/techdocs.ts index cca8cd06c3..a4671f24a5 100644 --- a/plugins/techdocs-node/src/stages/generate/techdocs.ts +++ b/plugins/techdocs-node/src/stages/generate/techdocs.ts @@ -97,7 +97,7 @@ export class TechdocsGenerator implements GeneratorBase { logger: childLogger, logStream, siteOptions, - runAsDefaultUser + runAsDefaultUser, } = options; // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url @@ -172,7 +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 + defaultUser: runAsDefaultUser, }); childLogger.info( `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`, From 7e36b794d80be4b01bc3deceb2251f53f62181e8 Mon Sep 17 00:00:00 2001 From: Kamil Zainal Date: Mon, 23 Oct 2023 16:46:21 +0100 Subject: [PATCH 4/4] Run `build:api-reports` Signed-off-by: Kamil Zainal --- packages/backend-common/api-report.md | 1 + packages/techdocs-cli/cli-report.md | 1 + plugins/techdocs-node/api-report.md | 1 + 3 files changed, 3 insertions(+) diff --git a/packages/backend-common/api-report.md b/packages/backend-common/api-report.md index f4d430ccbd..f0ab48c162 100644 --- a/packages/backend-common/api-report.md +++ b/packages/backend-common/api-report.md @@ -683,6 +683,7 @@ export type RunContainerOptions = { workingDir?: string; envVars?: Record; pullImage?: boolean; + defaultUser?: boolean; }; export { SearchOptions }; diff --git a/packages/techdocs-cli/cli-report.md b/packages/techdocs-cli/cli-report.md index 890718b0d2..8f2233b158 100644 --- a/packages/techdocs-cli/cli-report.md +++ b/packages/techdocs-cli/cli-report.md @@ -38,6 +38,7 @@ Options: --omitTechdocsCoreMkdocsPlugin --legacyCopyReadmeMdToIndexMd --defaultPlugin [defaultPlugins...] + --runAsDefaultUser -h, --help ``` diff --git a/plugins/techdocs-node/api-report.md b/plugins/techdocs-node/api-report.md index 656db6ae36..912e5b666b 100644 --- a/plugins/techdocs-node/api-report.md +++ b/plugins/techdocs-node/api-report.md @@ -55,6 +55,7 @@ export type GeneratorRunOptions = { siteOptions?: { name?: string; }; + runAsDefaultUser?: boolean; }; // @public