Skip to content
This repository has been archived by the owner on Dec 12, 2019. It is now read-only.

Latest commit

 

History

History
165 lines (117 loc) · 6.98 KB

README.md

File metadata and controls

165 lines (117 loc) · 6.98 KB

WARNING - This is not an official GOV.UK repository. It is also a WIP and could receive breaking changes at any time.

govuk-docker

An alternative way to to develop on GOV.UK.

diagram

Introduction

The GOV.UK website is a microservice architecture, formed of many apps working together. 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 tests, start a debugger, publish a document end-to-end e.g.

# Run whitehall rake plus any required dependencies (DBs)
whitehall$ gdr default rake

# Start content-tagger rails plus a minimal backend stack
content-tagger$ gdr backend

# Start content-publisher rails plus an end-to-end stack
content-publisher$ gdr e2e

The above examples make use of an alias to reduce the amount of typing; the full form is govuk-docker run-this. In the last two commands, the app will be available in your browser at app-name.dev.gov.uk.

Setup

First make sure the following are installed on your system:

  • dnsmasq to make app-name.dev.gov.uk work
  • docker and docker-compose, fairly obviously
  • git if you're setting everything up from scratch
  • A directory ~/govuk in your home directory

Start with the following in your bash config (aliases optional).

alias gd="govuk-docker"
alias gdr="govuk-docker run-this"
alias gdd="govuk-docker run-this default"
alias gdb="govuk-docker build-this"

export PATH=$PATH:~/govuk/govuk-docker/bin

Now in the govuk directory, run the following commands.

git clone git@github.com:benthorner/govuk-docker.git
cd govuk-docker

# Expect this to take some time (around 20 minutes)
make

Then create or append to the following and restart dnsmasq.

# /etc/resolver/dev.gov.uk
nameserver 127.0.0.1

# /usr/local/etc/dnsmasq.conf (bottom)
address=/dev.gov.uk/127.0.0.1

User Needs

The aim of govuk-docker is to meet the following primary need.

As a developer on GOV.UK apps
I want a GOV.UK environment optimised for development
So that I can develop GOV.UK apps efficiently

However, this high-level statement hides a great number of specific needs, which also help to clarify the design decisions for govuk-docker. These lower-level needs and associated decisions are set out in separate documents.

Compatibility

The following apps are supported by govuk-docker to some extent.

  • ⚠ asset-manager
  • ⚠ content-data-admin
    • TODO: Missing support for a webserver stack
  • ✅ content-publisher
  • ⚠ content-store
  • ⚠ content-tagger
  • ⚠ government-frontend
  • ✅ govspeak
  • ⚠ govuk-developer-docs
  • ✅ govuk-lint
  • ✅ govuk_app_config
  • ❌ govuk_publishing_components
  • ✅ miller-columns-element
  • ✅ plek
  • ✅ publishing-api
  • ❌ router
  • ✅ router-api
  • ✅ signon
  • ⚠ static
  • ✅ support
  • ⚠ support-api
  • ⚠ whitehall
    • Who knows, really - several tests are failing, lots pass ;-)
    • Rake task to create a test taxon for publishing is not idempotent
    • Placeholder images don't work as missing proxy for /government/assets

FAQs

How to: diagnose and troubleshoot

Sometimes things go wrong or some investigation is needed. As govuk-docker is just a bunch of docker config and a CLI wrapper, it's still possible to use all the standard docker commands to help fix issues and get more info e.g.

# tail logs for running services
gd logs -f

# get all the running containers
docker ps -a

# cleanup all govuk-docker services
gdd

# get a terminal inside a service
gdrd bash

How to: add a new service

Here's an example commit that does just that.

https://github.com/benthorner/govuk-docker/commit/1cd31a5fa3469cce47637db81f17ca1b03d72f89

How to: change a service e.g. upgrade Ruby

This will usually involve editing a Dockerfile, for things like system packages or new language versions; or a docker-compose.yml file, for things like environment variables and dependencies on other services. When a Dockerfile changes, the associated image needs to be rebuilt, which can be done in the service directory by running gdb.

How to: setup a specific service

If a new service has been added to govuk-docker, first pull the latest version to get the changes. One way to setup the new service would be to run make, but this goes through every service and might take a while. A faster way is to do this:

# auto-clone any new services
make clone

# setup the specific service(s)
make -f my_service/Makefile

How to: update everything!

Sometimes it's useful to get all changes for all repos e.g. to support finding things with a govuk-wide grep. This can be done by running make pull, followed by make setup to ensure all services continue to run as expected.