Skip to main content
  1. Home
  2. Apps
  3. govuk-docker
Last updated: 16 Jan 2025

govuk-docker: How Tos

👉 Check the troubleshooting guide if you have a problem.

How to: get back to a clean slate

If you encounter an issue with your Docker setup and you've already exhausted all other ideas, here's a quick one-liner that stops and removes absolutely everything. You can then follow the govuk-docker README instructions for make-ing your app again.

docker stop $(docker ps -a -q) && docker rm $(docker ps -a -q) && docker rmi $(docker images -q) -f && docker volume prune && docker container prune && docker image prune && docker network prune && docker system prune --all --volumes

How to: reduce typing with shortcuts

Typing the full commands is likely to get tiring. We've added a couple of lightweight helper scripts alongside govuk-docker, which figure out the application you're running based on the name of the current directory.

# full commands
govuk-docker run content-publisher-lite bundle exec rake
govuk-docker up content-publisher-app

# shortcuts
# assuming you're in the content-publisher directory
govuk-docker-run bundle exec rake
govuk-docker-up

Here are some suggested aliases that make things even shorter.

alias gd="govuk-docker"
alias gdr="govuk-docker-run"
alias gdu="govuk-docker-up"
alias gdbe="govuk-docker-run bundle exec"

How to: work with local gems

Provide a local gem path relative to the location of the Gemfile you're editing:

gem "govuk_publishing_components", path: "../govuk_publishing_components"

How to: replicate data locally

There may be times when a full database is required locally. The following scripts in the bin directory allow replicating data from integration:

  • replicate-elasticsearch.sh
  • replicate-mongodb.sh APP-NAME
  • replicate-mysql.sh APP-NAME
  • replicate-postgresql.sh APP-NAME

You will need to assume-role into AWS using the gds-cli before running the scripts. For example, to replicate data for Content Publisher, run:

# as an AWS PowerUser...
gds aws govuk-integration-poweruser --assume-role-ttl 3h ./bin/replicate-postgresql.sh content-publisher

# as an AWS User...
gds aws govuk-integration-readonly --assume-role-ttl 3h ./bin/replicate-postgresql.sh content-publisher

All the scripts, other than replicate-elasticsearch.sh, take the name of the app to replicate data for.

Draft data can be replicated with replicate-postgresql.sh draft-content-store and replicate-mongodb.sh draft-router.

If you want to download data without importing it, set the SKIP_IMPORT environment variable (to anything).

Troubleshooting

The replication scripts might fail for the following reasons:

  • pv not being installed. This is used to display a progress bar. On macOS, you can install pv using Homebrew.
  • Running out of space in Docker. This might result in an error like ERROR 1114 (HY000) at line 11768: The table 'govspeak_contents' is full. If you see this, you could do either or both of the following:
    • If you're okay with removing some or all of your Docker containers, images, and possibly volumes and other data, run docker system prune.
    • If you have enough spare space on your local machine, allocate more space to Docker. Using Docker Desktop, this setting is under Settings > Resources > Advanced > Resource Allocation > Virtual disk limit.

How to: set environment variables

While most environment variables should be set in the config for a project, sometimes it's necessary to set assign one or more variables at the point of running a command, such as a Rake task. This can be done using env e.g.

govuk-docker run content-publisher-lite env MY_VAR=my_val bundle exec rake my_task

How to: debug a running Rails app

Normally it's enough to run a Rails app using govuk-docker up. To get a debugger console for a specific app or one of its dependencies, we need to attach an interactive terminal to the running container.

# find the container name
govuk-docker ps

# attach to the container
docker attach govuk-docker_content-publisher-app_1

# awesome debugging stuff
...

# detach from the container
CTRL-P CTRL-Q

Note that many of the apps run using the Puma web server, which by default runs in cluster mode. This causes problems with using the debugger console. Puma routes the stdout from multiple processes back into the main container stdout, so the effect is often that keystrokes appear to be "lost" while output from non-paused processes is prioritised. To fix this, you can set the WEB_CONCURRENCY environment variable on the container to 0. That will force Puma to run in single process mode.

How to: use a custom working directory

GOV.UK Docker should respect the following environment variables:

  • $GOVUK_ROOT_DIR - directory where app repositories live, defaults to $HOME/govuk
  • $GOVUK_DOCKER_DIR - directory where the govuk-docker repository lives, defaults to $GOVUK_ROOT_DIR/govuk-docker
  • $GOVUK_DOCKER - path of the govuk-docker script, defaults to $GOVUK_DOCKER_DIR/bin/govuk-docker

How to: enable production JSON logs in development

  • Set GOVUK_RAILS_JSON_LOGGING to "true" in docker-compose.yml for the application you would like to enable the logs' behaviour for.

How to: publish a finder and specialist documents to test finders end-to-end locally

See How to Publish Content to a Finder in GOV.UK Docker

How to: Re-run make without branch checks

If you have already run make for a project recently, and just want to re-run it without it checking for updates to all dependent repositories (for example if you do not have a stable internet connection), you can set the SKIP_BRANCH_CHECKS environment variable:

SKIP_BRANCH_CHECKS=1 make my-app