Versions Compared

Old Version 14

changes.mady.by.user Michel El Hajj

Saved on

compared with

New Version Current

changes.mady.by.user Antoine Hage

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

Introduction

SOAJS Environments are each equipped with a registry that contains information such as security encryption phrases, logging configuration, domain information, infrastructure deployment driver and how to connect to it ... etc

In Addition 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 componentsextend the default registry and allow you to have add custom entries that you need in your code.

The registry is built upon deploying a service and is pulled from the database and cached in memory . It is for every microservice that launches in the environment. The registry is then 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
    1. Step 1: General Information
    2. Step 2: Environment deployment method
    3. Step 3: Advanced deployment settings
    4. Step 4: Nginx settings
    5. Step 5: Create and validate
    • Edit Environment

    You can learn more about SOAJS registry and what it offers on this page.



    Objective

    1. Managing Registries
      1. Edit Registry
      2. Key Security Update
    2. Custom Registry
    3. Access the Registry in the code
    Create New Environment




    Managing Registries
    Anchor

    createEnv

    manageReg

    createEnv

    manageReg

    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  Anchorstep1step1
    • 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)

    Image Removed

    Step 2: Environment deployment method  Anchorstep2step2

    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.

    Image Removed
    Step 3: Advanced deployment settings  Anchorstep3step3

    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.

    Image Removed

    Step 4: Nginx settings  Anchorstep4step4

    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

    Image Removed

    Step5: Validate and create  Anchorstep5step5

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

    Note

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

    Image Removed

    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  AnchoreditEnveditEnv

    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 propertiespillar, you will notice that in the left sidebar a drop down appears in RED. This drop down contains the codes of all the environments you have created so far. 

    Click on Registries Module, the registry of the environment you have selected in the drop down show up.

    From that interface you can learn about all the configuration that this registry currently offers to all the microservices and daemons that are running in this environment.

    Every time you create a new environment, SOAJS creates a registry for it and stores it in the core database by default.

    Edit Registry 
    Anchor
    editEnv
    editEnv

    You can edit the registry of an environment and update all the settings it contains except the environment code.

    Some of the settings get updated once you trigger the reload registry maintenance operation of the services running in this environment whereas other settings require you restart the services so that the effect takes place.

    Either way, the UI interface displays and elaborates which settings requires a service restart and which don't.


    Key Security Update
    Anchor
    keySecUpdate
    keySecUpdate

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

    This section is highly sensitive as it allows you to change the tenant key security encryption phrase that is used to encrypt tenant all the tenants that have keys associated with this environment.

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

    1. Flag all old keys for this environment as deprecated
    2. 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 configsettings.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

    loads via Nginx, otherwise all the calls that the UI makes after this event will fail since the key it contains is now deprecated.

    The same behavior happens in every environment, once you change the security phrase, make sure to update the interfaces & devices that integrates with your APIs by changing the key values to the newly generated ones otherwise all calls to your APIs will fail.


    Note:

    Concerning the Dashboard UI Interface, the settings.js that the default SOAJS dashboard uses resides in: https://github.com/soajs/soajs.dashboard/blob/master/.ui/configsettings.js and the default external key is on line 16.3.

    The wizard will inform you about the update after it happens along with the instructions you should do to move forward. 




    Custom Registry
    Anchor
    customRegistry
    customRegistry

    Custom Registries 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.

    Image Removed

    allow you to extend the default registry add your own configuration entries.

    Custom registries:

    • Support all data types
    • Can be locked, thus only get modified by the creator or the root owner
    • Shared among environments
    • Plugged and Unplugged from the registry ( only plugged entries in the registry can be access via the code )
    Image Added


    Accessing the Registry in the code
    Anchor
    accessReg
    accessReg

    The registry provide private inputs configuration related to the environment the service/daemon is that services and daemons are operating in. These inputs are acquired from the registry via SOAJS object at runtime: req.soajs.registry and contain registry and custom registry settings.

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