Multiple Environments¶

Introduction¶

3forge AMI refines the software development life cycle and improves developers' abilities to write high impact code. It allows devs to make rapid changes and see iterative improvements which need to be maintained overtime. This document provides a general template to manage and ensure that the development of dashboards is properly maintained for multiple environments.

The following components of 3forge AMI will need to be managed: AMI Layouts, AMI DB Schemas, AMI Config Properties, AMI Datasources, Aeskey, Scripts, and AMI Libraries. There are also additional sections in this document which may be useful such as Source Control, and AMI Database persist data files.

Environments¶

We recommend that development teams create multiple environments as necessary when working with AMI. Here's a recommendation, modify as necessary:

DEV: This environment is for day to day rapid changes.

QA: This environment is for promoting DEV changes for testing.

UAT: This environment should be set up with testing data but production volumes, it is for pre-production testing.

PROD: This is your production environment.

You should configure a custom properties file for each environment.

Note: You may want to set up a failover production environment to provide a backup server if a production change is not performing as expected.

Alternative Folder Structure¶

Note: You may to set up the environment folders at the top level, in this document we set up the environment folders at section to show developers how to manage important files.

At the root level make as many environment folders as you need.

Inside each environment folder, you should create the following subfolders that need to be managed and any additional ones you need. The below is an example.

Layouts¶

One of the key files you need to maintain are the dashboard layouts. These layouts are json files that define how a layout is constructed in the 3forge AMI frontend.

For the purposes of managing multiple environments we will only be using the cloud layouts.

There are three main ways 3forge AMI supports saving files: a local user file, an absolute file, and as a file in your local cloud directory. Local files are where 3forge AMI developers can make and test changes that are only visible to them. Absolute layouts can be saved anywhere on the server's file system. Cloud layouts are shared layouts available to users who have access to them.

How to Manage Layout Files for Multiple Environments¶

By default cloud layouts are stored in your data/cloud directory. We recommend making a cloud directory for each environment and configuring your AMI instance to use the cloud directory for that environment.

Example: Cloud directory structure¶

Controlled by the property:

1	`ami.cloud.dir=path/to/cloud`

AMI Database Schemas¶

The AMI Database (AMIDB) is a core component of 3forge AMI. It allows you store and cache data for aggregations and analytics. The files that define the schema of AMIDB are amisql files.

There are two types of schema files, one is managed by 3forge AMI which allows the addition of new tables, procedures, triggers, and timers while AMI is running. The other schema files are preconfigured and any tables, procedures, triggers and timers defined in these files cannot be modified.

By default 3forge AMI only starts with the managed schema file located in data/managed_schema.amisql.

Schema Structure¶

We recommend creating a folder structure like below for managing your schema files across deployments. You should place your managed schemas and config schemas in these folders.

Properties¶

1 2	`ami.db.schema.config.files=path/to/configSchema.amisql,path/to/configSchema2... ami.db.managed.file=path/to/managed_schema.amisql`

Note

When defining config files, use a comma delimited format without spaces.

Configuration Properties¶

Configuration properties are located in your config directory. Each install contains the following default property files, which should NOT be modified:

1
2
3

root.properties - contains the default included property files
defaults.properties - contains the default properties
speedlogger.properties - contains the default logging properties

By default, you should create a local.properties file and place custom properties in it. To configure properties for each environment, they can make separate property files for each environment.

To use those property files they can use the #INCLUDE directive to include that property file.

Example: Properties Files¶

Note

Using folders is a good way to organize properties by environment.

Controlled by the property:

1	`#INCLUDE path/to/env.properties`

Datasources.dat and amikey.aes¶

The __DATASOURCE.dat file contains 3forge AMI's datasource connection properties. Datasource connection details may differ in each environment. Datasources are accessed through its name and are pointers to the datasource configuration which contains details such as datasource connection url.

Example __DATASOURCE.dat file¶

For example, if the dashboard is connected to a Mysql and a Kdb database, the file will contain two entries containing the connection details.

To ensure 3forge AMI connects to the intended datasources depending on the environment, we recommend creating a folder for each environment and place the __DATASOURCE.dat file in them. Lastly, we need to edit the environment specific property file to indicate the location of it.

Based on the screenshot below, the property for the dev environment would be:

1 2	`# //Inside dev.properties ami.db.persist.dir.system.table.__DATASOURCE=persist/dev`

For prod it would be:

1 2	`# //Inside prod.properties ami.db.persist.dir.system.table.__DATASOURCE=persist/prod`

Amikey.aes¶

It is very important you manage your amikey.aes properly. This key is used for encrypting the connection details for your 3forge AMI datasources. It is recommended you have different amikey.aes keys for each environment. By default the key is located in your persist directory.

This key can be configured through the property:

ami.aes.key.file=path/to/amikey.aes

Controlled by the properties:

1 2	`ami.db.persist.dir.system.table.__DATASOURCE=path/to/datasourcesfolder ami.aes.key.file=path/to/amikey.aes`

Scripts¶

The scripts folder contains the startup scripts for 3forge AMI. We recommend managing your start script in source control if you change or customize the start script. You might modify the start script to change the amount of memory 3forge AMI reserves and change the java Garbage collector, etc.

Libraries (Optional)¶

3forge provides many plugins for connecting to datasources and interfacing with other technologies. By default, these libraries get stored in the lib directory. It may be a good practice to enable revision control on the 3forge AMI lib directory, especially for production environments, in case it is necessary to conduct a rollback.

Source Control for Layouts¶

3forge provides a source control plugin for AMI layouts. This is set up on the AMI server. We recommend that each AMI Developer create a separate branch with the developer's userid as the branch name. They should pull from the main branch and merge into the main branch when submitting change.

Persist Data¶

3forge stores the AMI Database data files by default in the persist folder. This can be configured through the property:

1	`ami.db.persist.dir=path/to/your/persist`

Do not want to check this into version control - these files can be very large.