Skip to content

do not prevent dev server startup if docsite fails

Warren Gifford requested to merge docsite-startup-not-fatal-dev into main

Created by: sqs

docsite runs in local dev on http://localhost:5080 and shows you a live preview of what will be deployed to https://docs.sourcegraph.com from your branch.

Previously, if docsite failed to start up, it would terminate all other dev processes in the Procfile. These problems are hard to troubleshoot because there are tons of log lines, and knowing which one was the first fatal error is tough (especially since the other processes print out suspiciously error-like messages when they are terminated in the middle of their startup). This caused confusion and surprise in https://sourcegraph.slack.com/archives/C07KZF47K/p1602187321225200?thread_ts=1602187037.224300&cid=C07KZF47K.

The most common reasons why docsite would fail to start are: invalid docsite.json config (such as invalid JSON syntax) or invalid redirects syntax (such as not starting the from-path with a /). These errors will still be caught in CI (because it runs docsite check), but now they will no longer prevent dev server startup. You will see a message error starting docsite like this:

10:54:52                           docsite | # Doc site is available at http://localhost:5080
10:54:52                           docsite | invalid redirects line: "foo bar"
10:54:52                           docsite | error starting docsite
10:54:52                           docsite | Terminating docsite

And then you'll need to fix the issue and run .bin/goreman run restart docsite or just restart the entire dev server script.

You should only be in this situation if you or someone else made docsite's config invalid. But this will happen, and there will probably be docsite bugs that make startup fail for other reasons, so this is a nice way to make them less painful. (And if you were just editing docsite's config files, you'll probably know where to look for this error message in the logs.)

It would be nice for goreman to handle this case better for all subprocesses, since docsite is not the only thing that can cause confusion like this. But this is definitely an improvement.

Merge request reports

Loading