Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 31 Mar 2021

govuk-docker: make-1

DEPRECATED: much of what follows was written before we adopted a PR/ADR mechanism for making changes in this repo. Needs may have changed since they were written here, so what follows should only be used to provide historical context.

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

This is a thorough but non-exhaustive list of the needs for developing in the GOV.UK ecosystem. All of the needs should be independent of the decisions that try to address them, which is why none refer to govuk-docker specifically.

Format:

As a developer on I want So that

Using the word 'service' instead of 'app' is a reminder that the GOV.UK ecosystem includes libraries, as well as runnable apps. Where a need is specific to an app, which is usually a web app, the word 'app' is used instead.

Learning GOV.UK

As a new developer on GOV.UK I want to quickly get all the active GOV.UK repos So that I can work with them locally

Decisions made to support this need: make-clone

As a new developer on GOV.UK I want to understand how the services are connected So that I can understand the service I'm working on

Decisions made to support this need: docker-compose

As a new developer on GOV.UK I want to understand the dev tools I'm using So that I can use them correctly and debug issues

Decisions made to support this need: make-files, docker-compose, cli-echo, docker-binding

Getting Started

As a new developer on a GOV.UK service I want to setup my environment without help So that I don't feel like a burden on my team

Decisions made to support this need: make-idempotent

As a new developer on a GOV.UK service I want to install the packages for the service So that I can run service commands (e.g. rake)

Decisions made to support this need: docker-dockerfiles, docker-context, make-files, docker-stacks

As a new developer on a GOV.UK app I want to initialise the databases for the app So that I can run the test suite that uses them

Decisions made to support this need: docker-stacks, make-files

As a new developer on a GOV.UK app I want to initialise the databases for the app So that I can manually test the app (e.g. in browser)

Decisions made to support this need: docker-stacks, make-files

Getting Updates

As a developer on a GOV.UK service I want to install the latest packages for the service So that I can continue to run service commands

Decisions made to support this need: docker-stacks, docker-lockfiles, docker-bundle, cli-runthis

As a developer on a GOV.UK service I want to install the language version for the service So that I can continue to run service commands

Decisions made to support this need: docker-imagetag, cli-buildthis

As a developer on GOV.UK services I want to get/update all active GOV.UK repos So that I can search across all codebases

Decisions made to support this need: make-idempotent, make-clone

Running Services

As a developer on a GOV.UK app I want to start a web server for the app So that I can manually test the app

Decisions made to support this need: docker-stacks, docker-bindmount, docker-binding

As a developer on a GOV.UK app I want to navigate to the app in my browser So that I can manually test the app

Decisions made to support this need: web-nginx, web-dnsmasq

As a developer on a GOV.UK app I want to run the app against supporting APIs So that I can manually test the app

Decisions made to support this need: docker-stacks, web-nginx, make-setup

As a developer on a GOV.UK app I want to run the app against an end-to-end stack So that I can manually test user journeys

Decisions made to support this need: docker-stacks, web-nginx, make-setup, rails/rails#36486

As a developer on a GOV.UK app I want to run the app against a draft-specific stack So that I can manually test user journeys

Decisions made to support this need: docker-stacks, web-nginx, make-setup, rails/rails#36486

As a developer on a GOV.UK app I want to change code without restarting the server So that I can efficiently assess the outcome

Decisions made to support this need: docker-mount1

As a developer on a GOV.UK app I want to run an debugger in the web server So that I can investigate a bug

Decisions made to support this need: docker-debugger

As a developer on a GOV.UK service I want to run a service-specific task (e.g. rake task) So that I can manually test the task

Decisions made to support this need: docker-stacks, cli-env

As a developer on a GOV.UK service I want to view the logs for the service So that I can investigate a bug (e.g. in a test)

Decisions made to support this need: docker-mount1

Automating Tests

As a developer on a GOV.UK service I want to run the entire test suite So that I can test the service works

Decisions made to support this need: docker-dockerfiles, docker-bindmount, cli-runthis

As a developer on a GOV.UK service I want to run a debugger in the tests So that I can investigate a bug

Decisions made to support this need: docker-debugger

As a developer on a GOV.UK service I want to run one or more specific tests So that I can efficiently test changes

Decisions made to support this need: docker-stacks, cli-runthis

As a developer on a GOV.UK service I want to write tests that behave predictably So that I can be confident they will pass on CI

Decisions made to support this need: docker-stacks

As a developer on a GOV.UK service I want to test a change spread over multiple services So that I can verify the services all work together

Decisions made to support this need: docker-mount2

Other Needs

As a developer on a non-GOV.UK service I want to not use a GOV.UK-specific environment So that I can run non-GOV.UK service commands

Decisions made to support this need: cli-exists

As a developer on a GOV.UK service I want to run commands with minimal typing So that I can develop more efficiently

Decisions made to support this need: make-setup, cli-exists, cli-runthis, cli-aliases, cli-buildthis, docker-bundleexec

Contributing

As a developer on a new GOV.UK service I want to update my environment to support it So that I can meet all of my other needs

Decisions made to support this need: make-clone, make-files, docker-compose

As a developer on a changing GOV.UK service I want to update my environment to support it So that I can meet all of my other needs

Decisions made to support this need: make-files, docker-compose, docker-aliases