Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise troubleshooting guidance #434

Merged
merged 4 commits into from
Nov 18, 2020
Merged

Revise troubleshooting guidance #434

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
df49596
Rewrite general app troubleshooting steps
Nov 17, 2020
ff01074
Fix typo in DNS troubleshooting instructions
Nov 17, 2020
3ba910e
Clarify final suggestion for debugging DNS
Nov 17, 2020
521c165
Remove unnecessary sub-sections
Nov 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 19 additions & 7 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,33 @@ bin/doctor

### Diagnose general issues with a project/app not working

* Make sure you run all commands via GOV.UK Docker.

```
# make sure GOV.UK Docker is up-to-date
git pull
govuk-docker-run bundle install
govuk-docker-run rake db:migrate
```

* Check if one of the dependencies is the problem.

# make sure the project is built OK
make <project>
> A common problem for dependencies is when you've previously `git pull`ed the repo, but haven't run `bundle install` or `rake db:migrate`. The logs for the dependency will show if this is the problem.

```
# check if any dependencies have exited
docker ps -a

# tail logs for running services/dependencies
# check logs for an exited dependency
govuk-docker logs -f publishing-api-app
```

* Try cleaning up and running your command again.

```
# stop all apps and their dependencies
govuk-docker down

# try clearing all containers / volumes
govuk-docker rm -sv
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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...!"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, thanks for explaining.

# make sure GOV.UK Docker is up-to-date
git pull
```

### Diagnose issues with `dev.gov.uk` domains not resolving
Expand Down