Revise troubleshooting guidance #434
Conversation
Previously these encouraged needless re-"make"-ing and "rm"-ing of containers. Two of the specific problems we have experienced are: - People not realising *all* commansds need to be run in a container - People not realising a problem is due to a failed dependency This rewrites the general app troubleshooting steps to advocate a more thoughtful approach to debugging - vs. "nuke everything"!
Previously this was quite vague, as it was unclear how "seeing what is changing" would help someone debug.
Previously I added these thinking it would help organise the guide, but with only one unique (and unlikely) section on installation, I don't think it adds any value right now.
There was a problem hiding this comment.
Have had a read and have a couple of suggestions below.
An aside: one note I made from yours & Huw's talk the other week was govuk-docker-up app-live for looking at live data. That may not be the exact command or purpose, but it was new to me and I wrote it down - can't see any further detail about it in the repo though. Is it documented somewhere? :)
|
|
||
| # try clearing all containers / volumes | ||
| govuk-docker rm -sv |
There was a problem hiding this comment.
I know you want to encourage people to diagnose and fix errors 'properly', but sometimes if you're in a bind and need to get something working quickly, this is just the easiest option. I'd really like you to leave it in, even if it's caveated with "You really shouldn't have to do this...!"
There was a problem hiding this comment.
I agree there is a need to have a clean slate. The govuk-docker down command I've suggested is actually equivalent to this, but has the advantage of being easier to explain and write down.
Does that help address your concern?
There was a problem hiding this comment.
Sure, thanks for explaining.
|
Thanks for the review @ChrisBAshton. I think I may have addressed your comments with a bit more explanation, but let me know if you'd like me to clarify the commits, for example. The |
We've [discussed adding this before](#434 (review)), and shied away from it in favour of more focussed troubleshooting. But sometimes folks just want a quick and easy task to reset things - so let's add this in.
https://trello.com/c/i3Y2vAua/188-documentation-on-how-to-troubleshoot-apps-failing-to-start-in-govuk-docker
This PR is a review of the general troubleshooting guidance
for apps, which we know is unhelpful for some people.
Please see the commits for more details.