feat(techdocs-cli): Allow passing docker extra args to @techdocs/cli serve and serve:mkdocs

Signed-off-by: Mathias Geat <[email protected]>

Author: maff

docs/features/techdocs/cli.md

@@ -83,6 +83,8 @@ Serve a documentation project locally in a Backstage app-like environment
 Options:
   -i, --docker-image <DOCKER_IMAGE>        The mkdocs docker container to use (default: "spotify/techdocs")
   --docker-entrypoint <DOCKER_ENTRYPOINT>  Override the image entrypoint
+  --docker-option <DOCKER_OPTION...>       Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12"
+                                           (can be added multiple times).
   --no-docker                              Do not use Docker, use MkDocs executable in current user environment.
   --mkdocs-port <PORT>                     Port for MkDocs server to use (default: "8000")
   -v --verbose                             Enable verbose output. (default: false)

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

@@ -215,6 +215,10 @@ export function registerCommands(program: Command) {
       '--docker-entrypoint <DOCKER_ENTRYPOINT>',
       'Override the image entrypoint',
     )
+    .option(
+      '--docker-option <DOCKER_OPTION...>',
+      'Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12" (can be added multiple times).',
+    )
     .option(
       '--no-docker',
       'Do not use Docker, run `mkdocs serve` in current user environment.',
@@ -237,6 +241,10 @@ export function registerCommands(program: Command) {
       '--docker-entrypoint <DOCKER_ENTRYPOINT>',
       'Override the image entrypoint',
     )
+    .option(
+      '--docker-option <DOCKER_OPTION...>',
+      'Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12" (can be added multiple times).',
+    )
     .option(
       '--no-docker',
       'Do not use Docker, use MkDocs executable in current user environment.',

packages/techdocs-cli/src/commands/serve/mkdocs.ts

@@ -62,6 +62,7 @@ export default async function serveMkdocs(opts: OptionValues) {
     port: opts.port,
     dockerImage: opts.dockerImage,
     dockerEntrypoint: opts.dockerEntrypoint,
+    dockerOptions: opts.dockerOption,
     useDocker: opts.docker,
     stdoutLogFunc: logFunc,
     stderrLogFunc: logFunc,

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

@@ -93,6 +93,7 @@ export default async function serve(opts: OptionValues) {
     port: opts.mkdocsPort,
     dockerImage: opts.dockerImage,
     dockerEntrypoint: opts.dockerEntrypoint,
+    dockerOptions: opts.dockerOption,
     useDocker: opts.docker,
     stdoutLogFunc: mkdocsLogFunc,
     stderrLogFunc: mkdocsLogFunc,

packages/techdocs-cli/src/lib/mkdocsServer.test.ts

@@ -64,6 +64,39 @@ describe('runMkdocsServer', () => {
         expect.objectContaining({}),
       );
     });
+
+    it('should accept custom docker options', async () => {
+      await runMkdocsServer({
+        dockerOptions: [
+          '--add-host=internal.host:192.168.11.12',
+          '--name',
+          'my-techdocs-container',
+        ],
+      });
+
+      expect(run).toHaveBeenCalledWith(
+        'docker',
+        expect.arrayContaining([
+          'run',
+          '--rm',
+          '-w',
+          '/content',
+          '-v',
+          `${process.cwd()}:/content`,
+          '-p',
+          '8000:8000',
+          '-it',
+          '--add-host=internal.host:192.168.11.12',
+          '--name',
+          'my-techdocs-container',
+          'spotify/techdocs',
+          'serve',
+          '--dev-addr',
+          '0.0.0.0:8000',
+        ]),
+        expect.objectContaining({}),
+      );
+    });
   });
 
   describe('mkdocs', () => {

packages/techdocs-cli/src/lib/mkdocsServer.ts

@@ -22,6 +22,7 @@ export const runMkdocsServer = async (options: {
   useDocker?: boolean;
   dockerImage?: string;
   dockerEntrypoint?: string;
+  dockerOptions?: string[];
   stdoutLogFunc?: LogFunc;
   stderrLogFunc?: LogFunc;
 }): Promise<ChildProcess> => {
@@ -45,6 +46,7 @@ export const runMkdocsServer = async (options: {
         ...(options.dockerEntrypoint
           ? ['--entrypoint', options.dockerEntrypoint]
           : []),
+        ...(options.dockerOptions || []),
         dockerImage,
         'serve',
         '--dev-addr',