Configuration development environment

To create a production deployment of i2 Analyze, you must develop the i2 Analyze configuration. The production deployment process describes a process of using different development environments to produce your i2 Analyze configuration. For more information about the environments, see Deployment phases and environments.

The analyze-deployment-tooling repository enables you to create a development environment that comprises a containerized deployment of i2 Analyze. The containerized deployment enables you to switch between deployment patterns easily and redeploy changes in a consistent manner.

Process overview:

Accept the licenses
Install the CA certificate
Create a config template
Create a custom config that you can deploy into a development environment
Use the environment to develop the i2 Analyze configuration

If you have already deployed a config and you want to create a new custom config from the template, go to Creating a development config.

Prerequisites

Before you create the configuration development environment, you must configure the analyze-deployment-tooling repository.
For more information, see Getting started with the analyze-deployment-tooling repository.
To edit files and run commands, use VS Code. If you have not already got it open, follow the steps in Set up development environment to do so.

Accepting the licenses

Before you can use i2 Analyze and the tools, you must read the license agreement and copyright notices then accept them.
1. To accept the license agreement, change the value of the LIC_AGREEMENT variable to ACCEPT in the licenses.conf file.
  To read the license, open the file in the pre-reqs/i2analyze/license directory.
Before you can use Microsoft SQL Server, you must accept the license agreement and the EULA. For more information about using the MSSQL_PID and ACCEPT_EULA environment variables, see Configure SQL Server settings with environment variables on Linux
1. To accept the license in this environment, change the value of the MSSQL_PID and ACCEPT_EULA environment variables. The variables are in the licenses.conf file.

For example, update the licenses.conf file to match:

LIC_AGREEMENT=ACCEPT
MSSQL_PID=Developer
ACCEPT_EULA=Y

Installing the certificate

To access the system, the machine that you are connecting from must trust the certificate that it receives from the Liberty container.

To enable trust, install the /environment-secrets/generated-secrets/certificates/externalCA/CA.cer certificate as a trusted root certificate authority in your browser and operating system's certificate store.

For information about installing the certificate, see:
- Windows: Install Certificates with the Microsoft Management Console
- MacOS:
  - Add certificates to a keychain using Keychain Access on Mac
  - Change the trust settings to Always Trust
- FireFox:
  - In the settings menu, type View Certificates and open it. Then, click Import and locate the CA.cer file.
  Note: If you are using a Mac and want to access the deployment from a Windows VM, you must install the certificate in your Windows VM.

Creating a config

Before you can deploy the environment, create a config from the template:

Copy the config-development directory (including the sub-directories) from /templates to the /configs directory.
You can rename the config-development folder to a custom config name or use the default value. The name of the directory is used to determine which config to deploy, it is recommended to use a short name with no spaces, special characters, or capital letters.
The directory structure is:
```
- configs
    - <config_name>
        - configuration
        - database-scripts
        - utils
```
The /configs/<config_name>/utils/variables.conf file contains variables that are used when you deploy the environment with this config. You can specify values for the following variables:
- The DEPLOYMENT_PATTERN variable specifies the deployment pattern for the deployment of i2 Analyze in the environment. You can specify:
  - schema_dev - An i2 Connect gateway only deployment that you can use to develop your data and security models
  - istore - Information Store
  - i2c - i2 Connect gateway only
  - cstore - Chart Store
  - i2c_istore - i2 Connect gateway and Information Store
  - i2c_cstore - i2 Connect gateway and Chart Store
    
    For more information about the i2 Analyze deployment patterns, see: Components.
- The following variables specify the database dialect and port used to connect from the host machine:
  - DB_DIALECT specifies the database management system to use. The possible values are sqlserver or postgres. The default value is postgres.
  - HOST_PORT_DB specifies the port that you use to connect to the database from the host machine. For sqlserver use 1433. For postgres use 5432. The default value is 5432.
- The following variables specify the ports that are exposed to the host machine for each component of i2 Analyze. Each variable has a default value:
  - HOST_PORT_SOLR specifies the port that you use to connect to the Solr Web UI from the host machine. By default, 8983.
  - HOST_PORT_I2ANALYZE_SERVICE specifies the port that you use to connect to the deployment from the host machine. By default, 9443.
  - HOST_PORT_PROMETHEUS specifies the port that you use to connect to the Prometheus UI from the host machine. By default, 9090.
  - HOST_PORT_GRAFANA specifies the port that you use to connect to the Grafana UI from the host machine. By default, 3500.
  For example, to deploy with the i2 Connect gateway only for schema development and to use the default ports:
```
DEPLOYMENT_PATTERN="schema_dev"
DB_DIALECT="postgres"
HOST_PORT_DB=5432
HOST_PORT_SOLR=8983
HOST_PORT_I2ANALYZE_SERVICE=9443
HOST_PORT_PROMETHEUS=9090
HOST_PORT_GRAFANA=3500
```

Specifying the schema and charting schemes files

To deploy i2 Analyze, you must provide a schema and charting scheme. The i2 Analyze toolkit includes example files that you can use as a starting point, or you can use existing files.

For more information about the example schemas, see Example schemas.

Choose an example schema and associated charting scheme as your starting point from the pre-reqs/i2analyze/toolkit/examples/schemas/<locale> directory.
Copy the chosen schema and charting scheme to your configs/<config_name>/configuration directory.
Remove the existing schema.xml and schema-charting-schemes.xml files. Then, rename your chosen schema file to schema.xml and your charting scheme to schema-charting-schemes.xml.

Specifying the security schema, user registry, and command access control files

To connect to an i2 Analyze deployment, you must provide a security schema and user registry. To control access to features and enable to use of the administrator endpoints, provide a command access control file.

The i2 Analyze toolkit includes example files that you can use as a starting point.

For more information about the example files, see Example schemas.

Copy and overwrite the example security-schema.xml, user.registry.xml, and command-access-control.xml files from the pre-reqs/i2analyze/toolkit/examples/security directory to your configs/<config_name>/configuration directory.

Deploying your config in the environment

Run the deploy command to deploy and start your environment:
```
deploy
```

After a successful deployment, a success message is displayed that includes the URL to use to connect to the deployment.

You can run only one config at a time. When you run the deploy command, it stops any containers on the Docker network. If you are deploying with the same config, it update the images and recreates the containers to update the environment with any configuration changes.
If you have more than one config, you must provide the name of the config to deploy by using the -c parameter and specify the name of the config directory. For example to deploy the config-development config, deploy -c config-development. For more information, see Managing configs.

Accessing the system

To connect to the deployment, the URL to use is: https://i2analyze.eia:9443/opal

Note: If you are using the schema_dev or i2c deployment patterns, you must connect using Analyst's Notebook.

Log in as a user that is specified in the user registry file. If you are using the example user registry, the example user has the following credentials:

The user name is Jenny
The password is Jenny

What to do next?

After you deploy your environment, you can start to develop the i2 Analyze configuration.

Using your environment for configuration development:

Developing schemas in your configuration development environment
After you develop your schema files, you can develop the rest of the i2 Analyze configuration.
Developing the rest of the configuration