GOV.UK development environment using Docker 🐳
GOV.UK development environment using Docker.
The GOV.UK website uses a microservice architecture. Developing in this ecosystem is a challenge, due to the range of environments to maintain, both for the app being developed and its dependencies.
The aim of govuk-docker is to make it easy to develop any GOV.UK app. It achieves this by providing a variety of environments or stacks for each app, in which you can run commands, and the app itself.
First make sure you have the following dependencies.
Next, add the following line to your bash/zsh config.
# in ~/.bashrc or ~/.zshrc export PATH=$PATH:~/govuk/govuk-docker/exe
echo $SHELL if you’re not sure which shell you use. After saving, you will need to run
source ~/.bashrc or
source ~/.zshrc to apply this change to your current terminal session.
~/govuk , run the following setup commands.
git clone email@example.com:alphagov/govuk-docker.git cd govuk-docker bundle install bin/setup
Then make sure you give Docker enough resources.
Running GOV.UK applications can be resource intensive. To give Docker more resources on Mac, click the Docker whale icon in the macOS menu bar, select ‘Preferences’. We suggest the following minimum resources:
- 6 CPUs
- 12 GB RAM
- 64GB+ Disk
Check out the how-to guide to customise your setup.
Do this the first time you work on a project:
Each project provides a number of ‘stacks’ for different use cases. You can see the stacks for a project in its config file. To provide consistency, all projects should follow these conventions for stacks:
This stack provides only the minimum number of dependencies to run the project code. This is useful for running the tests, or a Rails console, for example.
Do this to run the tests for a project:
govuk-docker run collections-publisher-lite bundle exec rake
This stack provides the dependencies necessary to run an app e.g. in a browser. If the app is a web app, you will then be able to visit it in your browser at
Do this to start a GOV.UK web app:
govuk-docker up collections-publisher-app
Variations on the
app stack are allowed where necessary such as:
- app-draft: used for testing the authenticating-proxy against a draft version of the router app.
- app-live: used to test a read-only frontend app against live GOV.UK APIs (avoids having to replicate data locally).
- app-account: used to enable integrations with a local account manager app prototype and attribute store. Currently a part of the GOV Accounts trial
app stacks also depend on a
worker stack, to run asynchronous tasks [example].
Check out the CONTRIBUTING guide.