Registries

Introduction

The registries module provides the ability to create & configure environments registries (one registry per environment) and this configuration can be reloaded during runtime without any downtime or restart needed.

SOAJS also provides the ability to have a custom registry for each environment where you can add additional configuration that is not supported by the default SOAJS components.

The registry is built upon deploying a service and is cached in memory. It is reloaded when the caching limit runs out. Changes you make take effect once the registry is auto reloaded or if you force a reload registry maintenance operation.

Objective

Create New Environment

Head to the Deploy pillar → Registries and click on Add new environment, follow the wizard and a new environment will be created.

By default, SOAJS is deployed with Dashboard Environment in place.

Whenever you create a new environment, SOAJS clones the clusters and deployment configuration from the Dashboard environment and merges them with the custom information you supply.

Step 1: General Information

Provide a code for you environment (this code is unique)
Provide a description for your environment
Enter the domain associated with this enviornment
Enter the API prefix of the specified domain ("api" is the default value)
Enter the site prefix of the specified domain ("site" is the default value)

Step 2: Environment deployment method

There is four deployment method:

Existing Settings:

Deploy this environment using the same deployment settings of another environment that you select from a dropdown list.

Docker:

In case you chose Docker, you have to provide the following: Cloud provider, docker port, docker internal port, docker network name and docker certificates

Kubernetes:

In case you chose kubernetes, you have to provide the following: Cloud provider, kubernetes port, kubernetes secret token, kubernetes namespace value, kubernetes namespace mode and nginx deployment mode.

Manual:

Deploy Everything Manually on your Local Machine or a your Custom Server.

Environment Security:

Provide a secret phrase to encrypt the tenants keys that will access the environment.

Persist your session in this environment by adding a cookie secret, session name and session secret.

Ready made services:

This will deploy the controller service in this environment automatically, so choose the controller deployment mode, memory limit, catalog recipe and the branch you want to deploy the controller from.

The controller acts as a gateway to all the microservices deployed in the same environment it operates in, Read More.

Testing & simulation:

If turned off, then this environment isn't sensitive and you can test your services using Swagger Simulator in it.

If turned on, then this environment is sensitive and you can't test your services using Swagger Simulator in it.

Deploy Nginx in this environment:

Set the memory limit per instance.

Let us create a recipe for you or use an existing one for deployment. In case you chose to create a new one, we will give you the ability to add a custom UI to be associated with this Nginx.

Nginx is an HTTP server also used for upstream arriving requests to the controllers of the environment it operates in.

Provides 2 entry points by default:

API:
domain name that uses the upstream to forward requests to available controllers
Site:
domain name that loads a static content interface

Step5: Validate and create

Finally, validate all your inputs, then press create environment. A progress bar will appear showing the progress.

Make sure not to refresh this page while the progress bar is shown!!

Once an environment is created, its Code is added automatically to the Red Menu in the top left sidebar of the interface. You can juggle between environments at any stage using the same Dashboard UI interface; no need to login to multiple locations.

Edit Environment

When editing an environment, you can update all the information inserted in Step 1 and Step 3 except the environment code and the Controller deployment settings.

Plus you can configure in depth every field in the registry. Click here to learn more about the registry and its properties.

Key Security Update

While editing your environment, you notice a section at the bottom with a highlighted Note box above and whose content is related to tenant key security.

This section allows you to change the tenant key security that is used to encrypt tenant keys with.

Changing the security phrase in any environment will trigger a background process that loops around all the tenants you have and:

Flag all old keys for this environment as deprecated
Generate new keys for this environment and update all the tenants affected.

If the environment happens to be Dashboard, SOAJS will prompt you with a new external key value that YOU MUST CHANGE in the config.js of the UI that was used by the dashboard Nginx. Otherwise if you logout from the dashboard, you will never be able to log back in.

Currently the config.js that the default SOAJS dashboard uses resides in: https://github.com/soajs/soajs.dashboard/blob/master/ui/config.js and the default external key is on line 16.

Custom Registry

Custom Registries are accessible after you create an environment and provide an JSON editor so you can enter any configuration you desire.

Add New Custom Registry:

In General tab, choose a name as a key, then the value can be a text or a JSON.

In settings tab, you can plug this custom registry so it becomes accessible, you can lock it so only the admin and the creator can modify it and you can share it with other environments.

Configure:

This button is for editing a custom registry.

Accessing the Registry in the code

The registry provide private inputs related to the environment the service/daemon is operating in. These inputs are acquired from the SOAJS object at runtime: req.soajs.registry

You can read in depth all the properties and information that the registry supplies inside the SOAJS Space → Registry section.