Skip to content

Latest commit

 

History

History
125 lines (86 loc) · 5.63 KB

production.md

File metadata and controls

125 lines (86 loc) · 5.63 KB
Raw

Deploying the production environment

Overview

The Design System is a static site which is generated by Metalsmith.

When the main branch changes, Github Actions will build the static site by running npm run build. As long as that succeeds, the contents of the deploy directory will then by uploaded to our application on GOV.UK Platform as a Service (PaaS). GOV.UK PaaS uses the open source Cloud Foundry project and exposes parts of their API.

We use nginx as a simple web server.

Github Actions

Configuration

The Github Actions CI workflow is configured in .github/workflows/ci.yaml. It will attempt to build the Design System, run the linter and run tests for every branch, but will only run the deploy step when on the main branch.

Most of the environment variables needed are set within each Github Action script. Any secrets can be viewed and changed within the Github UI (requires admin access).

Deployment

The Github Actions deployment script is detailed in .github/workflows/ci.yaml

We log into CloudFoundry using the configured environment variables. Before deploying, we cancel any existing deployments to prevent conflicts. When deploying, we use healthchecks to check that the /canary path returns a 200 response, which indicates that the app has been built successfully.

Hosting on GOV.UK Platform as a Service (PaaS)

We deploy to the govuk-design-system-origin app.

This app exists within the govuk-design-system organisation and the production space, and is deployed by the [email protected] user, the credentials for which can be found in our credential store.

We use an application manifest to configure the app name and the type of buildpack that we want to use.

See PaaS documentation for how to sign in and deploy apps.

nginx

We use the nginx buildpack. Nginx is configured in nginx.conf.

Content Delivery Network (CDN)

We use a CDN to cache the Design System assets and to terminate the SSL for the service domain. We don't cache HTML files.

This uses the cdn-route service provided by PaaS, which in turn provides a CloudFront distribution which we CNAME the service domain to.

Caching respects the expires headers that we send from nginx.

If you suspect issues with caching on the service domain, you can bypass the CDN by visiting https://govuk-design-system-origin.cloudapps.digital/.

Authentication is enabled on this domain to prevent indexing and minimise confusion. The username is origin and the password is badidea.

DNS

design-system.service.gov.uk is a subdomain of the service.gov.uk zone and is defined in alphagov/govuk-dns-config and deployed by the reliability engineering team]re-team using alphagov/govuk-dns.

Most other services are delegated as their own zones so that the service team have control over their own DNS, but we have opted to set up a subdomain instead because:

  • if delegated design-system.service.gov.uk would become the domain apex, which cannot then also be a CNAME.
  • the Design System is maintained by GDS, and so we would opt to use govuk-dns to configure our DNS regardless.
  • as a team of mostly Frontend developers we want to keep the amount of infrastructure we need to maintain to a minimum.

History

Use of the staticfile buildpack

We originally used the staticfile buildpack, but moved away because we found it too restrictive. For example, it was difficult to configure caching because the only place you could include nginx configuration was within a location block.

Proxying on GOV.UK

We explored hosting the Design System on gov.uk/design-system by configuring the Design System as a backend and route on GOV.UK's router.

This was abandoned because GOV.UK consistently does not use trailing slashes and is configured at the caching layer to strip them out, whilst the Design System consistently uses trailing slashes and nginx by default will automatically redirect to add them (because that's how static sites and directories with index files work). This caused an infinite redirect.

We considered changing the nginx configuration to match the behaviour of GOV.UK but decided against it because:

  • we would not be able to match this behaviour on other services we use, such as Netlify.
  • it would break relative URLs.

We considered modifying the caching layer to allow the Design System to keep its trailing-slashed URLs, but decided against it because:

  • it introduced a 'special case' and additional complexity to GOV.UK's configuration.
  • other parts of GOV.UK's infrastructure (such as their mirroring) make assumptions based on the lack of a trailing slash and relative URLs.