This project includes git submodules, so when running git clone you need to add the --recurse-submodules option. If you have already pulled, you can run git submodule init and then git submodule update --recursive instead. You might also need to run git submodule update --recursive if the submodule is updated because of a pull.

Install Docker: https://docs.docker.com/install/.

Increase the memory available to Docker to at least 4GB (instructions for Mac, Windows).

Copy the file in the root of the directory called .env-template. Rename the copy of the file to .env and fill in any environment variables. This .env file will be git ignored, so it is safe to add sensitive data. See the accounts section below for information on how to obtain some of the optional variables.

Add the following entry for Keycloak to your hosts file (instructions):

127.0.0.1   keycloak

Build and start-up the full project:

docker-compose up

Alternatively, you can run the specific component you're interested in using e.g. docker-compose up psd-web or docker-compose up cosmetics-web.

You'll then most likely want to run the Cosmetics setup steps or PSD setup steps.

When pulling new changes from master, it is sometimes necessary to run the following if there are changes to the Docker config:

docker-compose down && docker-compose build && docker-compose up

Projects in this repository use the GOV.UK design system. To aid it, the shared-web gem provides an implementation of some of the components - see the README for more details.

Docker shared volume performance is poor on Mac which can significantly affect e.g. asset compilation. You can use docker-sync to speed up runtime:

gem install docker-sync
docker-sync-stack start

You will have to install the docker server on Windows, and the docker client on WSL.

To make this work, make the current path look like a Windows path to appease Docker for Windows:

sudo ln -s /mnt/c /c
cd /c/path/to/project

(from https://medium.com/software-development-stories/developing-a-dockerized-web-app-on-windows-subsystem-for-linux-wsl-61efec965080) If the web container complains it can find files in the /app folder (e.g. bin/bundle), that might be sign you're in the wrong directory.

You may also want to setup docker-sync using these instructions.

The local developer instance of Keycloak is configured with the following default user accounts:

• PSD website: [email protected] / password
• Admin Console: admin / admin

Log in to the Keycloak admin console to add or edit users.

Ask someone on the team to create an account for you on the Int and Staging environments.

If you want to send emails from your development instance, or update any API keys for the deployed instances, you'll need an account for GOV.UK Notify

• ask someone on the team to invite you.

If you want to update any of the deployed instances, you'll need an account for GOV.UK PaaS - ask someone on the team to invite you.

We're using AWS to supplement the functionality of GOV.UK PaaS. If you want to update any of the deployed instances, you'll need an account - ask someone on the team to invite you. If you get an error saying you don't have permission to set something, make sure you have MFA set up.

Anything which is merged to master (via a Pull Request or push) will trigger the Travis CI build and cause deployments of the various components to the int space on GOV.UK PaaS.

Deployment to research environment does not currently happen automatically, for details see section "Research" in prototypes

Anything merged into the branch staging (only via a Pull Request) will cause Travis CI to instead build to the staging space. Please only do this if you are confident that this is a stable commit.

Anything merged into the branch prod (only via a Pull Request) will cause Travis CI to instead build to the prod space. Please only do this if you are confident that this is a stable commit.

Once you have a GOV.UK PaaS account as mentioned above, you should install the Cloud Foundry CLI (cf) from https://github.com/cloudfoundry/cli#downloads and then run the following commands:

cf login -a api.london.cloud.service.gov.uk -u XXX -p XXX
cf target -o beis-mspsds

This will log you in and set the correct target organisation. The login command without -u -p options will not work in some terminals, in particular git-bash. Passing username and password in one line will.

If you need to create a new environment, you can run cf create-space SPACE-NAME, otherwise, select the correct space using cf target -o beis-mspsds -s SPACE-NAME.

See antivirus/README.md.

See maintenance/README.md.

See keycloak/README.md.

See cosmetics-web/README.md.

See psd-web/README.md.

See infrastructure/README.md.

We use BrowserStack to test our service from a variety of different browsers and systems.

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.