Getting started with the analyze-containers repository

Prerequisites

You can run the code in the analyze-containers 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, 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-containers/releases/tag/v2.9.1.

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

    1. On Windows, copy the analyze-containers-2.9.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-containers-2.9.1.tar.gz

      mv analyze-containers-2.9.1/ analyze-containers

i2 Analyze minimal toolkit

  1. Download the i2 Analyze V4.4.3 Minimal for Linux.
  2. Rename the i2analyzeMinimal_443.tar.gz file to i2analyzeMinimal.tar.gz, then copy it to the analyze-containers/pre-reqs directory.

Note:

  • If you used the analyze-containers 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 Premium

  1. Download i2 Analyst's Notebook Premium version 10.0.0.

  2. Install i2 Analyst's Notebook Premium 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 Premium on a Windows virtual machine.

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

Modifying the hosts file

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

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

    • On Windows, open an Administrator Command Prompt and run Notepad.exe C:\Windows\System32\drivers\etc\hosts to edit the hosts file.
    • On MacOS, run sudo vi /etc/hosts to edit the hosts.

  2. Add the following lines to your hosts file:

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

If you deploy on MacOS, for your virtual machine to connect to i2 Analyze, complete the following:

  1. On your MacOS terminal, run ifconfig and identify the IP address for your virtual machine in a section such as vmnet1. 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.

Visual Studio Code

The repository is designed to be used with VS Code to create the development environment.

  1. Download and install VS Code

    • On Windows, when prompted to Select Additional Tasks during installation select the Add to PATH option so you can easily open a folder in WSL using the code command.
    • On MacOS, after you install VS Code, add it to your PATH. For more information, see Launching from the command line.

  2. Install the Dev Containers extension

  3. On Windows, use the following instructions to open the folder in WSL.

    1. Install the WSL extension
    2. Press F1 and type WSL: Connect to WSL and select it.

  4. 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-containers directory. For example: /home/<user-name>/analyze-containers.
    If you are prompted, click Trust Folder & Continue.

  5. 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-containers repository, use the VS Code integrated terminal. To open the integrated terminal, click Terminal > New Terminal.

Install analyze-containers

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: