Deploy a UI Stack

This page details how to create and deploy a UI deployment. Currently, the reference deployments are cloud and staging.

UI deployments follow the 'deployment' convention.
See UI Deployments for details of the various UIs currently available.

The UI Stack is comprised of the following services:

  • React UI

  • API Gateway

  • ArangoDB

  • Infra APIs

  • Grafana

  • Dashboard Generators

Playbook

The gateway.yml playbook will deploy most of this stack in one go. However, Grafana requires some manual configuration to create some of the required Ansible variables, so this needs to be done manually first.

i.e.

  • Run the _grafana_upgrade.yml playbook first

  • Set up the organisations and api keys in Grafana manually

  • Update the relevant Ansible group_vars files with these values

  • Run gateway.yml

Create a Deployment

If you need to create a new deployment, the easiest approach is to copy the cloud deployment and modify it. You will find this as a directory in the Ansible hosts section.

Now, review the preamble:

deployment_id: <deployment_id>
deployment_name: <DeploymentName>
deploy_level: prod
tld: smartermicrogrid.com
tld_internal: "{{false}}"
tld_public: "{{false}}"
Var Details Examples

deployment_id and deployment_name

Anything you like that does not conflict with an existing deployment or infra

badger_wood and Badger Wood

deploy_level

A hint as to whether this is a production or development deployment

prod or dev.

tld

DNS tld

dgcsedv.com or smartermicrogrid.com.
As we’re talking UIs, you will likely want smartermicrogrid.com.
dcgsdev.com would be for deployments which are only viewed internally, e.g a dev version.

tld_internal and tld_public.

Deprecated. Leave these as false unless you really know what you’re doing (and creating new TLDs!).

false

Hosts Configuration

The Ansible host file configurations for these deployments follow the form:

; Physical Devices
[<Hostname>]
<hostname>.dgcsdev.com
...


; Characterisations
[ec2:children]
<Hostname>
...

; Installation
[deployment:children]
ec2


; Infra Services
[<infra_id>_dashboard_generator_server:children]
<Hostname>
[<infra_id>_api_server:children]
<Hostname>

...


; Services
[ui_server:children]
<Hostname>

[gateway_api_server:children]
<Hostname>

[grafana_server:children]
<Hostname>

[api_server:children]
<infra_id>_api_server
...

[dashboard_generator_server:children]
<infra_id>_dashboard_generator_server
...


; Infras
[<infra_id>:children]
<infra_id>_dashboard_generator_server
<infra_id>_api_server

...
Section Intent

Physical Devices

Sets up the the server references and their urls.

Characterisation

Creates the conventional ec2 group and any other characteristics of the target machine.

Installation

Creates the required deployment group and any other appropriate behavioural variations.

Infra Services

Declares where all the infra-related service container should be deployed.
These services are one-to-one to a specific infra, and not multi-tenant.

Services

Declares the locations of the multi-tenant service containers.
It alo collects the infra-specific services together by service type.

Infras

Collects the infra-specific services together by infra.

Groups Vars

Some parts of the configuration are likely to be common. You will probably not need to modify these:

  • bitbucket_*

  • balena_*

  • keycloak_* - unless you actively want a new keycloak instance. In principle this shouldn’t be necessary as you can create 'Realms' in the existing keycloak.

ArangoDB

This section varies depending on if you are deploying a new arango instance or pointing at an existing one.

In either case there are also some common variables:

arangodb:
  id: arangodb
  user: 'xyz'
  password: "********"
  dbname: "<infra_id>"
Key Details

id

The service id for the arnago instance. Also used in the DNS mappings.

user

The db username

password

The db password

dbname

The database name.
Optional. Defaults to the infra id

Deploying a new ArangoDB

If you need to deploy an ArangoDB instance, you first need to have added an appropriate line in the hosts file:

[arangodb_server:children]
<HostReference>

In the deployment.yml you’ll need to augment the arangodb object with the following:

arangodb:
  ...
  version: 3.5.2
  ports:
    main: 11011
  volumes:
    data: /var/lib/dgcsdev/arangodb/data
    apps: /var/lib/dgcsdev/arangodb/extra
  docker_memory: 1GB

Update the version, ports and volumes to suit.

Using an existing ArangoDB

You will first need to log in to the arangodb instance and manually create the database with the dbname you have chosen (or the deployment id if you are using defaults).

Consider giving this database its own user as best practice for access permissions.

To reference an existing arangodb installation, augment the arangodb object with the following:

arangodb:
  url: <arangourl>
The arangodb conventionally created for the cloud deployment is ArangoDB, which can be reused if you provide a custom dbname.

Grafana

You can either use an existing Grafana instance, or create a new one.

In either case, you will need to Add An Infra to that instance.

Ansible Vars

Var Details

grafana_domain

Must match the UI domain for the sake of SSL certs and SSO. Conventionally this is therefore <ui_service_id>.<deployment_id>.<tld> for whichever deployment provisioned the instance, which will be ui.cloud.smartermicrogrid.com if you are reusing the cloud grafana instance.

grafana_url

Used for nginx proxying so that SSO and SSL certs work. It must therefore start with the `grafana_domain, but you can use whatever path suffix works for the nginx proxying. Conventionally, it is just https://{grafana_domain}/grafana.

UI

These vars should be fairly straightforward:

ui_service_id:      ui
ui_version:         17.7.3
ui_container_port:  8090

API Gateway

This section configures the API.

gateway_services_id: gateway
gateway_api:
  service_id:     api
  version:        0.6.4
  ports:
    container:    38800
    inspect:      18000
    healthcheck:  18400
  volumes:
    data: data

This is set up as a 'loop' to allow multiple gateway_api instances to server the gateway_services_id cluster. In reality, the only implementation of this at the moment is actually single-instance, so this may be a little over-engineered. Just be aware that the these variables impact the DNS creation, although the actual route in for the UI is via the UI’s base domain and routed through nginx to support SSL certs and CORS protection.

gateway_api.volumes.data is a directory name, and exists to avoid collision between multiple instances if they are created. If you have a single-instance deployment, you can leave this as-is.

Infras

The minimal structure for infra vars is:

useInfras: [<infra_id>, ...]

infras:
  <infra_id>: "{{infra_vars_object}}"
  ...

infra_apis_service_id:  api
infra_apis_version:     16.2.6
infra_apis:
  <infra_id>: "{{infra_api_vars_object}}"
  ...


dashboard_generators_service_id: 'dashboard_generator'
dashboard_generator_version: 11.4.1
dashboard_generators:
  <infra_id>: "{{infra_dashboard_generators_vars_object}}"
  ...

The *_id and *_version vars in this section are obviously required to deploy the referenced services.

useInfras explicitly includes the infras for which you want to build these services. The infras configurations do not automatically get used anywhere just because they have been defined. All configuration and deployment of infra-specific services is looped over this variable first, and only the matching infra vars are ever actually consumed.

See the Add an Infra docs for usage of infras, infra_apis and dashboard_generators.

Running the Deploy

To run the deploy, use the scripts as outlined in Ansible Deployments.

DNS

You will need to set up the Route53 DNS manually for the time being.

Follow the Deployment Conventions regarding naming, and point the records at the host server’s public IP address.

Conventionally, the dns record should be ui.<deployment_id>.<tld>.

Keycloak

You will need to add the deployment’s urls to Keycloak’s expected origins.

  • Log in to Keycloak as the administrative user

  • Go to the Public realm

  • Go to Clients

  • For both the ui and grafana client:

    • Add this UI’s urls to Valid Redirect URIs and Web Origins and hit save.