Skip to main content
  1. Home
  2. Apps

Repository: govuk-docker

GOV.UK development environment using Docker 🐳

GitHub
govuk-docker
Ownership
#govuk-platform-engineering
Category
Utilities

README

GOV.UK development environment using Docker.

diagram

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.

RFC 106: Use Docker for local development describes the background for choosing Docker. See the list of projects which work with govuk-docker.

Installation

First make sure you have the following dependencies.

  • brew
  • git
  • A govuk directory in your home directory

Next, add the following line to your bash/zsh config.

# in ~/.bashrc or ~/.zshrc
export PATH=$PATH:${HOME}/govuk/govuk-docker/exe

Run 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.

Now in ~/govuk , run the following setup commands.

git clone git@github.com:alphagov/govuk-docker.git
cd govuk-docker
bin/setup

👉 Check the troubleshooting guide if you have a problem.

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.

Usage

Do this the first time you work on a project:

make [app-name]

…where app-name is the name of the app you want to build. For example, if you want to make collections-publisher you would run:

make collections-publisher

👉 Check the troubleshooting guide if you have a problem.

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:

The lite stack

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 [app-name]-lite bundle exec rake

👉 Check the troubleshooting guide if you have a problem.

The app stack

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 app-name.dev.gov.uk.

Do this to start a GOV.UK web app:

govuk-docker up [app-name]-app

👉 Replicate data locally (or use the app-live stack).

👉 Check the troubleshooting guide if you have a problem.

The app-* stacks

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).

Some app stacks also depend on a worker stack, to run asynchronous tasks [example].

Resources

Contributing

Check out the CONTRIBUTING guide.

Licence

MIT License