gds/govuk-mini-environment-admin - Build, deploy and manage mini GOV.UK environments

1. User Documentation
- 1.1. License
2. Developer Documentation

The GOV.UK Mini Environment Admin application can manage mini GOV.UK environments, deployed mostly on a single machine or system style container.

A GOV.UK environment is a connected collection of the various services. A complete environment would include all the publishing and admin applications, as well as all the other services. When creating a mini environment, you can choose to omit some services if they are unnecessary or undesired.

It is possible to create mini environments on the local machine (through using libvirt), or create them on rented infrastructure (from Amazon Web Services (AWS)).

1. User Documentation

1.1. License

The GOV.UK Mini Environment Admin is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The GOV.UK Mini Environment Admin is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU AfferoGeneral Public License along with the GOV.UK Mini Environment Admin. If not, see http://www.gnu.org/licenses/.

2. Developer Documentation

The GOV.UK Mini Environment Admin is a Ruby on Rails web application for managing mini environments. Terraform is used for the low level management of the environments, and this is connected to the web application through the use of the Que qweuing library, and terraform Ruby library.

2.1. Components

2.1.1. Web appliciation

The web application is responsible for:

User authenticating via the GDS:SSO Ruby library, which uses the GOV.UK Signon service.
Providing a easy to deploy mini environments through the Terraform configuration.
Storing the Terraform state, which Terraform fetches and updates using a Rest API.

All the persistent state is stored in a PostgreSQL database.

2.1.2. Queue workers

The queuing system uses the Ruby Que library, which stores the state in the PostgreSQL databae. The queues are where Terraform is run.

2.1.3. Terraform configuration

The Terraform configuration is split up by provider (libvirt or AWS).

2.2. Dependencies

The GOV.UK Mini Environment Admin has a number of dependencies.

2.2.1. Core Dependencies

The web application is written in Ruby using the Ruby on Rails framework. A number of additional Ruby gems are also required:

pg
terraform
que
git

The backends for AWS and libvirt use Terraform.

2.2.2. Useful additions

Rubocop and Coala

For static analysis and code linting.
rerun

Useful to run que with, e.g. rerun -d app que ./config/environment.rb.

2.3. Development Environment

The repository includes a minimal .envrc file for use with direnv. User specific customisation can be done through the .local.envrc file.

Unless you've already setup a sufficient development environment, you might want to use direnv to set this up. The following code for .local.envrc will setup the envionment to use a checkout of GNU Guix located at ../gnu-guix and a checkout of govuk-guix located at ../govuk-guix.

# To avoid $XDG_CONFIG_HOME/guix/latest from being used
export GUIX_UNINSTALLED="true"

GOVUK_GUIX_PATH="$(readlink -f "$PWD/../govuk-guix/.guix-package-path")"
GNU_GUIX_PATH="$(readlink -f "$PWD/../gnu-guix")"

export GUILE_LOAD_PATH="$GOVUK_GUIX_PATH:$GNU_GUIX_PATH"
export GUILE_LOAD_COMPILED_PATH="$GNU_GUIX_PATH"

export GUIX_PACKAGE_PATH="$GUILE_LOAD_PATH"

Table of Contents