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