Publish prototypes on the web
You can share prototypes made with the GOV.UK Prototype Kit by publishing them on the web using an MoJ service called Cloud Platform.
Note - This process can only be used to deploy prototypes based on the GOV.UK Prototype Kit. This process will not work for any other types of apps e.g. Design History. If in any doubt please contact #ask-cloud-platform, or speak to your development team before you follow these instructions.
Before you start
To publish a prototype you’ll need to:
- be a member of at least one GitHub team in the MoJ GitHub Organisation
- have the Cloud Platform CLI installed
- have a local development environment including a terminal and a git client/github desktop
We assume you will have:
- a github repository in the MoJ GitHub Organisation, with Gov.UK Prototype Kit code.
- a latest prototype kit code build using Node.js.
1. Copy (Clone) the
To create resources on the Cloud Platform, you need to raise a pull request against the cloud-platform-environments repository.
Create a copy of the cloud-platform-environments repository:
$ git clone firstname.lastname@example.org:ministryofjustice/cloud-platform-environments.git $ cd cloud-platform-environments
2. Create your prototype kit environment
In the Cloud Platform CLI run:
$ cloud-platform environment prototype create
You’ll be asked to name your prototype/namespace, which should be the name of your prototype github repository.
This name will be used as:
- the namespace which will be created on the Cloud Platform
- the github repository name, to push the secrets required to access Cloud Platform from your github repository
- the domain name your prototype kit will be published to
You must ensure that the namespace name should be the same as your prototype github repository and there is not already a namespace.
For example, if you choose
my-prototype as the name, you will create:
- a namespace on the Cloud Platform called
3. Raise a PR
After you have answered all the questions, the cloud-platform CLI will create several files in a folder called:
namespaces/live.cloud-platform.service.justice.gov.uk/[name you chose]
Create a new branch and add/commit the new folder to Git:
$ git checkout -b my-prototype $ git add . $ git commit -m "Added my-prototype prototype"
Push this branch to GitHub:
$ git push origin my-prototype
Note: Please replace
my-prototypein the commands above with the name you chose.
And then raise a pull request (PR) by following the instructions that will appear on GitHub in the cloud-platform-environments repository.
Once a member of the Cloud Platform team has approved your PR, merge it.
When you merge the PR, the Apply Pipeline will create your namespace and push the credentials required to publish the kit as github secrets in your GitHub repository.
4. Create your prototype kit deployment files
Create a copy of your prototype kit repository:
$ git clone email@example.com:ministryofjustice/<your-prototype-repository>.git $ cd <your-prototype-repository> $ git checkout main $ cloud-platform prototype deploy create
This will create the files to build and deploy your prototype kit to the environment you created in step 2 and 3.
The deployment files work only on the latest version of the prototype kit which we regularly update in the moj-prototype-template. Your deployment may break if your prototype kit is not the latest version.
Use the instructions to update your prototype kit to latest version
5. Push these files to github
$ git add . $ git commit -m "Add docker build and deployment files" $ git push origin main
If you dont have permissions to push directly to the main/default branch, create a branch and raise PR to have it approved and merge.
Create a new branch and add/commit the files to Git:
$git checkout -b my-branch $ git add . $ git commit -m "Add docker build and deployment files" $ git push origin my-branch
Once these files are pushed to your github repository, the prototype kit will be deployed using the github action that is run by your repository.
Look under “Actions” tab on your github repository UI for the progress of the deployment.
Your prototype will be deployed in the below url:
6. Publish prototype kit for changes on a specific branch
The github action file under
./github/workflows and the continuos deployment filenames are generated based on the git branch you are in.
To generate the files for a specific branch, checkout to the branch and run the same command
For example, if you branch is called
$ git clone firstname.lastname@example.org:ministryofjustice/<your-prototype-repository>.git $ cd <your-prototype-repository> $ git checkout tooling $ cloud-platform prototype deploy create
The files generated for deploying in specific branch are as below:
./.github/workflows/cd-tooling.yaml kubernetes-deploy-tooling.tpl Dockerfile .dockerignore start.sh
The docker build files
Dockerfile,.dockerignore, start.shwork only on the latest version of the prototype kit which we regularly update in the moj-prototype-template. Your deployment may break if your prototype kit is not the latest version.
If you want to skip the docker build files when deploying to a branch, you can add a
--skip-docker-files flag. For example:
$ cloud-platform prototype deploy create --skip-docker-files
Branch deployment and cleanup
When you create the deployment files using
step 5 for a branch, they are generated to deploy on that specific branch. If the branch is merged to the
main branch, these deployment files will get merged as well. You can do the cleanup by deleting the files specifically created for that branch.
Deleting your published prototype
When you no longer need your prototype to be published:
Note - These steps are to decommission the hosting infrastructure that your prototype is running on. This will not delete your prototype source code.
raise a PR removing your namespace folder from the
cloud-platform-environmentsrepository, and wait for it to be approved by a member of the Cloud Platform team
immediately before you merge the PR use the GitHub web interface to delete your repository
merge the PR
Your namespace will be removed from the Cloud Platform.