Managing the environment

The manage-environment command is used to manage the dev environment rather than specific configs. The actions that the script can complete include; backing up and restoring all configs, upgrading configs to a later version, and building connectors.

i2 Analyze version

In a the config dev environment and a containerized deployment, the images that are used for the containers are built for a specific version on i2 Analyze. To identify the version of i2 Analyze that a particular image is built for, inspect the the image.

To inspect the images, use the Docker extension in VS Code.
The liberty_configured_redhat & solr_redhat image includes the version number in the tag. For example: config-development-4.4.0.0

Each config includes a version file that reports the i2 Analyze version for that config. This value does not include the fix pack version number.
For example, the version file contains: SUPPORTED_I2ANALYZE_VERSION=4.4.0

The `manage-environment` command

The manage-environment command is used to manage to development environment rather than specific configs.

The following usage and help is provided for the manage-environment command:

Usage:
  manage-environment -t backup [-p <path>] [-i <config_name>] [-e <config_name>] [-b <backup_name>] [-y]
  manage-environment -t copy -p <path> [-i <config_name>] [-e <config_name>] [-y]
  manage-environment -t upgrade [-y]
  manage-environment -t update [-y]
  manage-environment -t link [-y]
  manage-environment -t stop [-i <component_name>] [-e <component_name>] [-y]
  manage-environment -t renew-certificates [-y]
  manage-environment -t renew-secrets [-y]
  manage-environment -t clean [-i <config_name>] [-e <config_name>] [-y]
  manage-environment -t connectors [-i <connector_name>] [-e <connector_name>] [-y]
  manage-environment -t extensions [-i <extension_name>] [-e <extension_name>] [-y]
  manage-environment -t duplicate-config -c <config_name> -n <new_config_name> [-l] [-y]
  manage-environment -h

Options:
  -t {backup}                                                       Backup the database for a config.
  -t {copy}                                                         Copy the dependencies for a config from the specified path, to the current analyze-deployment-tooling project.
  -t {upgrade}                                                      Upgrade all configurations from the specified path.
  -t {update}                                                       Update images.
  -t {link}                                                         Links shared configurations.
  -t {stop}                                                         Stops the running containers.
  -t {clean}                                                        Clean the deployment for a config. Will permanently remove all containers and data.
  -t {renew-secrets}                                                Renews secrets for the configuration development environment.
  -t {renew-certificates}                                           Renews certificates for the configuration development environment.
  -t {connectors}                                                   Build all connector images.
  -t {extensions}                                                   Build all extensions.
  -t {duplicate-config}                                             Duplicates a config.
  -l                                                                Duplicates a config in a shared repository and symlink it to analyze-deployment-tooling project.
  -i <config_name|extension_name|connector_name|component_name>     Name of the config, connector, extension or component to include for the task. To specify multiple values, add additional -i options.
  -e <config_name|extension_name|connector_name|component_name>     Name of the config, connector, extension or component to exclude for the task. To specify multiple values, add additional -e options.
  -b <backup_name>                                                  Name of the backup to create or restore. If not specified, the default backup is used.
  -p <path>                                                         Path to the root of an analyze-deployment-tooling project. Defaults to the current project path. Or /home/<user_name>/analyze-deployment-tooling in upgrade.
  -y                                                                Answer 'yes' to all prompts.
  -v                                                                Verbose output.
  -h                                                                Display the help.

Backup and restore

The backup and restore tasks allow you to back up and restore a number of configurations by using one command. To back up a single config, use the deploy command that is described in back up and restore.

To back up all of the configs in your environment, run:

manage-environment -t backup -b backup-202206

This creates a backup named backup-202206 for all configs in the environment.

Updating the Docker images

The update task pulls the latest images from Docker Hub and rebuilds the local images. Use this task to update the images in your environments. Images on Docker Hub are updated with security fixes and other updates. For more information, see Update the Docker images.

Upgrading

The upgrade task allows you to upgrade the configs in your environment to a later version of Analyze deployment tooling or i2 Analyze.
For more information, see Upgrading.

Duplicate a configuration

The duplicate-config task allows you to duplicate a configuration within the environment. This is useful if you want to create a new configuration that is similar to an existing configuration. The new configuration is created with the same settings as the existing configuration, but with a different name.

Run the following command:
```
manage-environment -t duplicate-config -c <config-name> -n <new_config-name>
```
Where <config-name> is the name of the config that you want to duplicate and <new-config-name> is the name of the new config.

If the configuration that you are duplicating is from a shared configuration, specify the -l option to create the new configuration in the shared configuration location. Otherwise, the new configuration is created locally.

Copying configurations

The copy task allows you to copy configs from one development environment to another.

Update the path-configuration.json file to reference the path where you installed the i2 Analyze toolkit:
1. Add a name and the path to your i2 Analyze toolkit as the keys and values for the externalDirectories object.
  
  For example, to add /home/<user-name>/analyze-deployment-tooling-2 the path-configuration.json file contains the following:
```
{
"externalDirectories": [{
 "name": "containers-repo",
 "path": "/home/<user-name>/analyze-deployment-tooling-2"
}]
}
```

To update your environment to use the root directory, you must run the configure-paths command.

Reopen the analyze-deployment-tooling folder locally.
- On Windows press F1, type Dev Containers: Reopen Folder in WSL and select it.
- On MacOS press Cmd+Shift+P, type Dev Containers: Reopen Folder Locally and select it.
Open a terminal and run:
```
./scripts/configure-paths
```
Reopen the analyze-deployment-tooling folder in a dev container.
Press F1 (or Cmd+Shift+P in MacOS), type Dev Containers: Rebuild and Reopen in Container and select it
Run the following command:
```
manage-environment -p <path> -t copy
```
Where <path> is the absolute path to the root of another analyze-deployment-tooling repository that was added to the path-configuration.json file.

This script copies the following directories:
- backups
- configs
- connector-images
- environment-secrets
- gateway-schemas
- i2a-data
- i2a-extensions
- i2a-plugins
- additional-resources
  
  If you specify to include or exclude any configs by using the -i and -e options, only those config directories are copied but all assets are copied even if not referenced.

Building connectors

The connectors that are referenced by a config are built and deployed when that config is deployed. You can optionally build all connectors or a subset of the connectors by using the manage-environment command with the connectors task.

To build all of the connector images, run:
```
manage-environment -t connectors
```
To build a subset of the connector images, you can use of the include (-i) and exclude (-e) options.
For example:
```
manage-environment -t connectors -i connector_name_1 -i connector_name_2
```
This command only builds images for connector_name_1 and connector_name_2.
```
manage-environment -t connectors -e <connector_name_1> -e <connector_name_2>
```
This command builds the images for all connectors except connector_name_1 and connector_name_2.

Building extensions

The extensions that are referenced by a config are built and deployed when that config is deployed. You can optionally build all extensions or a subset of the extensions by using the manage-environment command with the extensions task.

To build all of the extensions, run:
```
manage-environment -t extensions
```
To build a subset of the extensions, you can use the include (-i) and exclude (-e) options.
For example:
```
manage-environment -t extensions -i extension_1 -i extension_2
```
This command only builds extension_1 and extension_2.
```
manage-environment -t extensions -e <extension_1> -e <extension_2>
```
This command builds all of the extensions except extension_1 and extension_2.

Stopping the environment

The stop task allows you to stop all the running containers in the environment. To start using the environment again, run the deploy command with your chosen config name.

Note: The stop task stops all containers in the eia network. Any containers that were created outside of the config dev environment that are connected to the eia network will be stopped. You must manually start these containers.

Cleaning a deployment

The clean task allows you to clean all configs by deleting all the containers and volumes. This is a destructive operation.

Linking shared configurations

The link task allows you to link configurations. For more information, see Managing shared configurations.

Renewing certificates

The renew-certificates task allows you to renew certificates for all configs.

Renewing secrets

The renew-secrets task allows you to renew secrets for all configs. Similar to renew-certificates task but also renews passwords.