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)).

* User Documentation

** 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/>.

* 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.

** Components

*** 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.

*** 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.

*** Terraform configuration

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

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

*** Core Dependencies

The web application is written in [[https://www.ruby-lang.org/][Ruby]] using the [[http://rubyonrails.org/][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.

*** 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=.

** Development Environment

The repository includes a minimal =.envrc= file for use with
[[https://direnv.net/][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=.

#+BEGIN_SRC shell
# 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"
#+END_SRC