Getting started with the analyze-deployment-tooling repository

Prerequisites

You can run the code in the analyze-deployment-tooling repository on Windows with Windows Subsystem for Linux and MacOS. The system requires being connected to the internet to download required repositories.
If you are running the project from an environment without an internet connection, you must first install in an online environment with the following instructions before moving to an offline system. For more information, see External dependencies.

Windows Subsystem for Linux (WSL)

If you are on Windows, you must use WSL 2 as the backend for Docker and to run the shell scripts in this repository.

  1. In an administrator Command Prompt, run the following command:

    wsl --install

  2. Restart your machine to complete the installation.

  3. After you restart, open the distribution. Press Start -> wsl
  4. You will be asked to create a User Name and Password for your Linux distribution.
    For more information, see Set up your Linux username and password.
  5. Ensure you can access the WSL filesystem from Windows explorer. In the address bar you can use \\wsl.localhost\Ubuntu. Additionally it is displayed in the Quick Access Toolbar, for example:
    Windows Quick Access Toolbar

Docker

  1. Install Docker Desktop for your operating system. For more information about installing Docker Desktop, see https://docs.docker.com/engine/install/#desktop.

  2. After you install Docker, allocate at least 5GB of memory to Docker to run the containers in the example deployment.

    On Windows, Docker is automatically allocated 8GB or 50% of available memory whichever is less.

    For more information about modifying the resources allocated to Docker, see:

Keep your Docker Desktop up-to-date as you use your system to ensure you receive stability, feature, and security updates.

Code

  1. Download the tar.gz from https://github.com/i2group/analyze-deployment-tooling/releases/tag/v3.0.1.

  2. Extract the tar.gz file by using the following steps:

    1. On Windows, copy the analyze-deployment-tooling-3.0.1.tar.gz file to your WSL filesystem. For example: \\wsl.localhost\Ubuntu\home\<user>

    2. Extract the tar.gz file (On Windows, run the commands from a WSL terminal. Start > wsl):

      cd /home/<user>

      tar -xzf analyze-deployment-tooling-3.0.1.tar.gz

      mv analyze-deployment-tooling-3.0.1/ analyze-deployment-tooling

i2 Analyze minimal toolkit

  1. Download the i2 Analyze V4.4.4 Minimal for Linux.
  2. Rename the i2analyzeMinimal_444.tar.gz file to i2analyzeMinimal.tar.gz, then copy it to the analyze-deployment-tooling/pre-reqs directory.

Note:

  • If you used the analyze-deployment-tooling repository with a previous version of i2 Analyze, overwrite the existing minimal toolkit.
  • To deploy a fix pack, download the minimal toolkit version of the fix pack and complete Step 2 above.

Analyst's Notebook

  1. Download i2 Analyst's Notebook version 10.

  2. Install i2 Analyst's Notebook on a Windows machine. Note: Ensure that you choose to install i2 Analyze Schema Designer as part of the installation process.

    Note: If you are running Docker on MacOS, you can install Analyst's Notebook on a Windows virtual machine.

    For more information, see Installing i2 Analyst's Notebook.

Development environment prerequisites

To deploy and develop an i2 Analyze configuration, you need to set up the development environment. Visual Studio Code is used as the IDE and you must modify your hosts file to connect to a deployment.

On Windows you can run the install-pre-reqs.bat script to install Visual Studio Code and modify the hosts file. If you are on MacOS manually set up the development environment.

Windows pre-requisites installation

The process for installing pre-requisites on Windows includes two stages:

  1. Manual Visual Studio Code installation
  2. Scripted pre-requisites installation

Manual Visual Studio Code installation

Download and install Visual Studio Code.

Scripted pre-requisites installation

The install-pre-reqs.bat script installs the required extensions and updates your hosts file. The script checks if you already have the prerequisites installed and does not overwrite them.

  1. Open Windows Explorer.
  2. Navigate to the analyze-deployment-tooling directory. For example, `\\wsl.localhost\Ubuntu\home\<user>\analyze-deployment-tooling.
  3. Right-click on the install-pre-reqs.bat file.
  4. Click Run as administrator.
  5. Ensure that the script ran successfully by checking the output in the command prompt window.
  6. Press any key to close the window.

MacOS pre-requisites installation

Install Visual Studio Code

  1. Download and install Visual Studio Code

  2. Install the Dev Containers extension

Modify the hosts file

To enable you to connect to a deployment, the Solr Web UI, the database, and the Prometheus Web UI, update your hosts file to include entries for the containers.

  1. Run the following commands to update the hosts file for your operating system:

    • run sudo vi /etc/hosts to edit the hosts.

  2. Add the following lines to your hosts file:

    127.0.0.1 i2analyze.eia
127.0.0.1 postgres.eia
127.0.0.1 prometheus.eia
127.0.0.1 solr1.eia
127.0.0.1 sqlserver.eia

For your for your virtual machine to connect to i2 Analyze, complete the following:

  1. On your MacOS, go to Settings > General > Sharing. Click the i information next to File Sharing. Turn on File Sharing and copy the IP address displayed. For example, 172.16.100.1.

  2. Then, on your Windows virtual machine add the same lines above to the file with the identified IP address. To edit the hosts file, open an Administrator Command Prompt and run Notepad.exe C:\Windows\System32\drivers\etc\hosts.
    For example 172.16.100.1 i2analyze.eia.

  3. To ensure that your hosts file is configured correctly, open a command prompt in your virtual machine and run: ping i2analyze.eia.
    If you get a successful response, your virtual machine is configured correctly.

Using Visual Studio Code

  1. On Windows, use the following instructions to use WSL.

    1. Press F1 and type WSL: Connect to WSL and select it.

  2. Press F1 (or Cmd+Shift+P in MacOS) and type Dev Containers: Open Folder in Container... and select it. In the file explorer, navigate to your analyze-deployment-tooling directory. For example: /home/<user-name>/analyze-deployment-tooling.
    If you are prompted, click Trust Folder & Continue.

  3. After the dev container starts, if you are prompted, click Install in the pop-up that is displayed that prompts you to install the recommended VS Code extensions.

Your config dev environment is correctly opened when the following is displayed in the bottom left-hand corner of the VS Code window:
Dev Container: Analyze Containers Dev
For more information about VS Code dev containers, see Developing in a container.

  1. To run the scripts in the analyze-deployment-tooling repository, use the VS Code integrated terminal. To open the integrated terminal, click Terminal > New Terminal.

Install analyze-deployment-tooling

To download all the required images and configure your environment, run:

  ./bootstrap

This command can take a while to run depending on your internet connection and the speed of your machine.

What to do next

To understand how the containerized environment is created, you can review the documentation that explains the images, containers, tools, and functions: