Skip to main content
Last updated: 7 Oct 2021

govuk-docker: Troubleshooting

Diagnose common issues when setting up GOV.UK Docker

Run the following command in ~/govuk/govuk-docker. Since this script makes use of Ruby Gems, you will need to install some additional dependencies in order to do this.


Diagnose database issues with a project/app not making

If you run make on an app inside govuk-docker and face any of the following database issues:

  • ActiveRecord::Migration is not supported
  • duplicate key error

...then it is likely that there is a conflict between the app and one of your existing volumes. This is because database contents are stored in a volume that the container uses, so when the container is recreated, it picks up the same data again.

The easiest resolution is to drop the database, e.g. govuk-docker run content-store-lite bundle exec rails db:mongoid:drop, and then try to make again.

A blunter solution would be to drop the volume altogether, by running docker volume rm VOLUME_NAME, where VOLUME_NAME can be derived from docker volume ls.

Diagnose general issues with a project/app not working

  • Make sure you run all commands via GOV.UK Docker.
govuk-docker-run bundle install
govuk-docker-run rake db:migrate
  • Try repeating the action. If you got a GdsApi::HTTPUnavailable or GdsApi::TimedOutException the first time around, it could mean that Publishing API wasn't ready in time, as unfortunately there's no way for govuk-docker to know when each dependency is ready.

  • Check if one of the dependencies is the problem.

A common problem for dependencies is when you've previously git pulled 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

# 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

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

Diagnose issues with domains not resolving

  • Check if works end-to-end
dig @

# output should contain...
#		0	IN	A
  • Check your /etc/resolver config is working
scutil --dns

# output should contain...
# domain   :
# nameserver[0] :
# port     : 53
# flags    : Request A records, Request AAAA records
# reach    : 0x00030002 (Reachable,Local Address,Directly Reachable Address)
  • Re-run the setup script and look for errors

Resolve issues caused by an existing Docker installation

You may get one of the following errors when running bin/setup.

Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
Could not symlink bin/docker-compose
Target /usr/local/bin/docker-compose
Error: It seems there is already an App at '/Applications/'.

This isn't a problem if you already have Docker/Compose installed, and the setup script will continue to run. If you like, you can remove your existing Docker/Compose and run bin/setup again.

Check if you are using Docker Compose V2

At time of writing, docker are trialing a version 2 of the compose command. It's been observed that after updating Docker, some developers are opted into using this experimental feature. Also at time of writing, using compose V2 has been observed to cause problems when using govuk-docker. Specifically it seems to not work against the nginx image we use.

To check if you're using compose V2 and turn it off:

  • open the docker dashboard UI
  • click the settings gear icon
  • go to "Experimental Features"
  • check if the "Use Docker Compose V2 release candidate" checkbox is checked
  • uncheck it if it is checked and save