techdocs serve does not work

[DanArlowski]

what:
when running techdocs serve it does not work

env:
MacOS 10.15.7

$ techdocs-cli --version
0.5.0
$ cat mkdocs.yml
site_name: 'site'
site_description: 'desc'

plugins:
  - techdocs-core

nav:
  - Overview:
      - goal: 'overview/goal.md'
$ npx --version               
6.14.13

logs:

$ techdocs-cli serve -v
info: Starting mkdocs server.
info: Waiting for mkdocs server to start...
verbose: [docker/mkdocs] INFO     -  Building documentation...
verbose: [docker/mkdocs] WARNING  -  Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please use a third party production-ready server instead.
verbose: [docker/mkdocs] INFO     -  Cleaning site directory
verbose: [docker/mkdocs] INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
verbose: [docker/mkdocs]   - index.md
verbose: [docker/mkdocs] INFO     -  Documentation built in 0.23 seconds
verbose: [docker/mkdocs] Traceback (most recent call last):
verbose: [docker/mkdocs]   File "/usr/local/bin/mkdocs", line 8, in <module>
verbose: [docker/mkdocs]     sys.exit(cli())
verbose: [docker/mkdocs]   File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1137, in __call__
verbose: [docker/mkdocs]     return self.main(*args, **kwargs)
verbose: [docker/mkdocs]   File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1062, in main
verbose: [docker/mkdocs]     rv = self.invoke(ctx)
verbose: [docker/mkdocs]   File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1668, in invoke
verbose: [docker/mkdocs]     return _process_result(sub_ctx.command.invoke(sub_ctx))
verbose: [docker/mkdocs]   File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1404, in invoke
verbose: [docker/mkdocs]     return ctx.invoke(self.callback, **ctx.params)
verbose: [docker/mkdocs]   File "/usr/local/lib/python3.8/site-packages/click/core.py", line 763, in invoke
verbose: [docker/mkdocs]     return __callback(*args, **kwargs)
verbose: [docker/mkdocs]   File "/usr/local/lib/python3.8/site-packages/mkdocs/__main__.py", line 173, in serve_command
verbose: [docker/mkdocs]     serve.serve(dev_addr=dev_addr, livereload=livereload, **kwargs)
verbose: [docker/mkdocs]   File "/usr/local/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 78, in serve
verbose: [docker/mkdocs]     server = config['plugins'].run_event('serve', server, config=config, builder=builder)
verbose: [docker/mkdocs]   File "/usr/local/lib/python3.8/site-packages/mkdocs/plugins.py", line 94, in run_event
verbose: [docker/mkdocs]     result = method(item, **kwargs)
verbose: [docker/mkdocs]   File "/usr/local/lib/python3.8/site-packages/mkdocs_monorepo_plugin/plugin.py", line 67, in on_serve
verbose: [docker/mkdocs]     buildfunc = list(server.watcher._tasks.values())[0]['func']
verbose: [docker/mkdocs] AttributeError: 'LiveReloadServer' object has no attribute 'watcher'
info: Waiting for mkdocs server to start...
info: Waiting for mkdocs server to start...
info: Waiting for mkdocs server to start...
info: Waiting for mkdocs server to start...
info: Waiting for mkdocs server to start...
info: Waiting for mkdocs server to start...
info: Waiting for mkdocs server to start...
info: Waiting for mkdocs server to start...
info: Waiting for mkdocs server to start...
error: mkdocs server did not start. Exiting. Try re-running command with -v option for more details.
Non zero exit code from child process

relevant issues:
mkdocs/mkdocs#2446

[dhenneke]

This was fixed in backstage/techdocs-container#16.

But I also had the problem today, because the techdocs-cli didn't automatically pull the newest image. After I did a docker pull spotify/techdocs, it worked.

Maybe we should add a --pull to this code @iamEAP?

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

Lines 32 to 46 in b972985

	"docker",
	[
	"run",
	"--rm",
	"-w",
	"/content",
	"-v",
	`'${process.cwd()}':/content`,
	"-p",
	`${port}:${port}`,
	dockerImage,
	"serve",
	"--dev-addr",
	`0.0.0.0:${port}`
	],

[iamEAP]

Maybe we should add a --pull to this code @iamEAP?

Alternative: should we lock a version to the default image? Believe this would auto-pull on updates, and would also prevent things from breaking unexpectedly on folks as we iterate on the underlying container.

[soapraj]

@iamEAP Curious on how to lock the docker image version for a release. By using a specific version here ?

[iamEAP]

Exactly.

[iamEAP]

...Although there's a spot in @backstage/techdocs-common that we'd probably want to update / keep in sync too. ...Perhaps we export the default docker image from TechDocs common and consume it here? 🤔

[emmaindal]

I can validate that the serve command works for latest version of the cli (0.6.1). But wanted to take some action on that it doesn't auto-pull the latest image currently.

Isn't it enough to just use spotify/techdocs:latest as the dockerimage instead of just spotify/techdocs?

Although that will of course break the cli if the techdocs-container breaks, so maybe not ideal?

[Fox32]

Isn't it enough to just use spotify/techdocs:latest as the dockerimage instead of just spotify/techdocs?

No, :latest is a mutable tag, I even think that Docker falls back to :latest if no tag is specified. Docker will only download it again if you instruct it to do so (e.g. via --pull) or by using a non mutable tag. Either versions are non mutable (e.g. :v1.0.0) or you even specify a fixed SHA for the image. Once concern about --pull is that it might pull to often and consume rate limiting, but I don't know exactly how it's done for Docker hub.

[emmaindal]

Now when its locked @iamEAP, an we close this issue or do we need to take some more actions here?

[iamEAP]

We still need to base the local default on the locked version exported by TechDocs common, but for that, we need to be able to pull down the latest TechDocs common. I think @andrewthauer was possibly looking at that, but perhaps we could collaborate on that more specifically?

[andrewthauer]

@iamEAP - I started looking at bumping techdocs-common to the latest version. but it includes some breaking changes. In the current state it would require exposing flags to configure all the available SCM options in backstage under the integrations app-config.yaml config. The code in techdocs-common now uses the ScmIntegrations code to compute the edit url, etc for the docs site.

The quickest way forward here is probably making this feature optional and not use it in techdocs-cli. However, I've been busy with other things so haven't been able to dive in much further.

[emmaindal]

Thanks for the update @andrewthauer, I'll start take a look at the edit button stuff and we can take it from there!