> For the complete documentation index, see [llms.txt](https://docs.idea-hpc.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.idea-hpc.com/first-time-users/install-idea/standard-installation.md).

# Standard Installation

The control plane runs only on ECS. Direct upgrades require 26.10.0 or newer on every deployed module. Use the 26.10.9 administrator to complete any older upgrade and ECS migration first. See the [recovery command](https://docs.idea-hpc.com/first-time-users/cluster-operations/update-idea-cluster/upgrade-cluster.md#recovery-with-the-26109-administrator).

Download the matching archive from the [GitHub release](https://github.com/cfs-energy/idea/releases) (replace `<VERSION>` with the release version):

| Operator platform   | Release file                             |
| ------------------- | ---------------------------------------- |
| macOS Apple silicon | `ideactl-v<VERSION>-darwin-arm64.tar.gz` |
| Linux ARM64         | `ideactl-v<VERSION>-linux-arm64.tar.gz`  |
| Linux x64           | `ideactl-v<VERSION>-linux-amd64.tar.gz`  |
| Windows x64         | `ideactl-v<VERSION>-windows-amd64.zip`   |

Each archive has a `.sha256` sidecar and is included in `SHA256SUMS`. Extract it to get one `ideactl` file (`ideactl.exe` on Windows). The Node runtime and deployment CLI are embedded; no Node or npm installation is required. Run `./ideactl about` on macOS/Linux or `.\ideactl.exe about` in PowerShell.

Windows releases have no code signing. SmartScreen may warn: after verifying the archive with `Get-FileHash -Algorithm SHA256` against the release checksum, choose **More info > Run anyway**, or run `Unblock-File .\ideactl.exe` in PowerShell before launching it. Organization policy may prevent this override.

{% hint style="warning" %}
Review [Pre-Requisites](https://docs.idea-hpc.com/first-time-users/install-idea/pre-requisites.md) section first
{% endhint %}

## Install IDEA from scratch

{% tabs %}
{% tab title="Linux/Mac" %}
**Option 1: Automatic installation**

Copy/Paste this command on your terminal to launch the installation

```sh
git clone https://github.com/cfs-energy/idea
cd idea
./idea-admin.sh quick-setup
```

**Option 2: Download the installer and execute it manually**

As an alternative, you can download `idea-admin.sh` via this <https://raw.githubusercontent.com/cfs-energy/idea/main/idea-admin.sh> and execute it on your Linux or Mac environment via `/bin/bash idea-admin.sh quick-setup`
{% endtab %}

{% tab title="Windows" %}
Installation of IDEA in Windows is managed by Powershell. Download and execute the following script on your local Windows workstation:

Note: This will only work on Windows 10/11 as Windows Server lacks support for Linux Containers.

```powershell
git clone https://github.com/cfs-energy/idea
cd idea
./idea-admin-windows.ps1 quick-setup
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
./idea-admin.sh utility offers many features. Refer to [IDEA CLI utility](https://docs.idea-hpc.com/developer-portal/idea-cli-utility.md) for more details.
{% endhint %}

Follow the installation wizard to install IDEA. During the installation, you will be prompted for various AWS parameters.

`quick-setup` proceed to a brand new deployment, if you are looking to re-use existing AWS resources running on your AWS environment (VPC, subnets ..), refer to [#install-idea-using-existing-aws-resources](#install-idea-using-existing-aws-resources "mention").

{% hint style="warning" %}
Run `export IDEA_ADMIN_AWS_CREDENTIAL_PROVIDER=Ec2InstanceMetadata` prior to `quick-setup` if you are planning to authenticate to AWS using IAM role and not IAM user.
{% endhint %}

<figure><img src="https://4178558898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff38qThSa0Aa40txosxbS%2Fuploads%2FEg8jcM7WIQkDmmr2XEG9%2Finstall_idea_standard_wizard_example.webp?alt=media&amp;token=fce8f7ea-5640-419e-9081-becfb8296d2a" alt=""><figcaption><p>Installation of IDEA is managed by a wizard.</p></figcaption></figure>

Installation will take anywhere between 30 to 80 minutes depending the module(s) you are planning to install. Connection strings will be displayed at the end of the installation

```
checking endpoint status for cluster: idea-test, url: https://idea-test-external-alb-1837136939.us-east-2.elb.amazonaws.com ...
+------------------------------+---------------------------------------------------------------------------------------------------+---------+
| Module                       | Endpoint                                                                                          | Status  |
+------------------------------+---------------------------------------------------------------------------------------------------+---------+
| Cluster Manager              | https://idea-test-external-alb-1837136939.us-east-2.elb.amazonaws.com/cluster-manager             | SUCCESS |
| eVDI                         | https://idea-test-external-alb-1837136939.us-east-2.elb.amazonaws.com/vdc                         | SUCCESS |
| Scale-Out Computing          | https://idea-test-external-alb-1837136939.us-east-2.elb.amazonaws.com/scheduler                   | SUCCESS |
+------------------------------+---------------------------------------------------------------------------------------------------+---------+
```

### Resume installation in case of failure

IDEA deployment creates multiple stacks based on modules selected for deployment. The total time of deployment can range anywhere between 40 mins to 1.5 hours.

After a CloudFormation stack is deployed for a module, the status of each module maintained in DynamoDB changes from **not-deployed** → **deployed**.

You can check the deployment status per module by running:

```
./idea-admin.sh list-modules  \
  --cluster-name <CLUSTER_NAME> \
  --aws-region <REGION>

# example:
./idea-admin.sh list-modules --cluster-name idea-dev1 --aws-region us-east-1
+----------------------------+------------------+--------+----------------------------+--------------+----------+
| Name                       | Module ID        | Type   | Stack Name                 | Version      | Status   |
+----------------------------+------------------+--------+----------------------------+--------------+----------+
| metrics                    | metrics          | stack  | idea-dev1-metrics          | 3.0.0-beta.1 | deployed |
| cluster-manager            | cluster-manager  | app    | idea-dev1-cluster-manager  | 3.0.0-beta.1 | deployed |
| directoryservice           | directoryservice | stack  | idea-dev1-directoryservice | 3.0.0-beta.1 | deployed |
| virtual-desktop-controller | vdc              | app    | idea-dev1-vdc              | 3.0.0-beta.2 | deployed |
| cluster                    | cluster          | stack  | idea-dev1-cluster          | 3.0.0-beta.2 | deployed |
| scheduler                  | scheduler        | app    | idea-dev1-scheduler        | 3.0.0-beta.1 | deployed |
| global-settings            | global-settings  | config | -                          | -            | deployed |
| analytics                  | analytics        | stack  | idea-dev1-analytics        | 3.0.0-beta.1 | deployed |
| bastion-host               | bastion-host     | stack  | idea-dev1-bastion-host     | 3.0.0-beta.1 | deployed |
+----------------------------+------------------+--------+----------------------------+--------------+----------+
```

If you encounter any errors during deployment, in one of the stacks, the default behavior is to rollback the deployment for that particular stack. Try to investigate the cause of the problem using the Event log displayed by CDK.

If you are able to identify and fix the problem, you can safely run the below command to re-trigger the installation. Process will resume automatically after the last known operation:

```
./idea-admin.sh deploy all \
  --cluster-name <CLUSTER_NAME> \
  --aws-region <REGION>
```

If only one module has failed, you can run `./idea-admin.sh deploy <MODULE_NAME>` directly.

## Install IDEA using existing AWS resources

As an alternative, you can install IDEA using existing resources running on your AWS environment such as VPC, Subnets, Filesystems, OpenSearch clusters and more.

To enable this mode, use `--existing-resources` as shown below:

```bash
./idea-admin.sh quick-setup --existing-resources
```

IDEA installer will guide you through the entire process during Step 3

<figure><img src="https://4178558898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff38qThSa0Aa40txosxbS%2Fuploads%2FlNFJhuU2Dxx6Fv86UCN2%2Finstall_idea_standard_existing_resources.webp?alt=media&amp;token=c6e8dae6-7137-4510-9f4a-36581b96362c" alt=""><figcaption><p>Select the resources you want to re-use via the installer CLI interface</p></figcaption></figure>

## Change default installation parameters

IDEA is 100% customizable and because of that, we cannot provide all the options via a single wizard. Follow these steps if you want to change the default parameters for any module.

1 - Proceed to the regular Installation via `idea-admin.sh quick-setup`

2 - Pause when the installer prompt you with **"Are you sure you want to update cluster settings db with above configuration from local file system?"**

<figure><img src="https://4178558898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff38qThSa0Aa40txosxbS%2Fuploads%2FvYWqDGCdFGT8YIDMFTpz%2Finstall_idea_standard_change_default.webp?alt=media&amp;token=1efbee45-1649-4281-880b-c3786a765b9e" alt=""><figcaption><p>Pause your installation and open a new terminal to edit the configuration</p></figcaption></figure>

At this point, open a new terminal and navigate to `` ~/.idea/clusters/<YOUR_CLUSTER_NAME>/<YOUR_REGION>/` ``

You should see `` `values.yml` `` and a `` `config` `` folder. `config` contains all settings which are module specific

```bash
ls ~/.idea/clusters/idea-test/us-east-2/config/
analytics       directoryservice    metrics
bastion-host        global-settings     scheduler
cluster         idea.yml        shared-storage
cluster-manager     identity-provider   vdc
```

3 - Update your parameter(s)

In this example, we will show you how to update the following parameters:

* vdc.dcv\_session.allowed\_sessions\_per\_user: Number of virtual desktops per user (default to 5)
* vdc.dcv\_session.instance\_types.allow: Control which EC2 families users can provision for virtual desktops. The default is `t3`, `g4ad`, `g6`, `g6e`, `g7`, `c8i`, `m6a`, `m6g`, `m7i`, `m8g`, `m8i`, and `r8g`. The `g7e` family has a driver mapping but is not in the default allow list.

The screen below (generated during `idea-admin.sh quick-setup` ) reports the default values for both sessions

<figure><img src="https://4178558898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff38qThSa0Aa40txosxbS%2Fuploads%2FfEs3H13AVlKF0Nhsi6A8%2Finstall_idea_standard_quick_setup_report.webp?alt=media&amp;token=d5e4a1dc-128f-42a6-91a1-1646b7e84ee1" alt=""><figcaption></figcaption></figure>

To update these parameters, edit \``` ~/.idea/clusters/<YOUR_CLUSTER_NAME>/<YOUR_REGION>/config/vdc/settings.yml` `` and update the relevant keys.

<figure><img src="https://4178558898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff38qThSa0Aa40txosxbS%2Fuploads%2F0ZFdkwQnXyHJ6Pg5epXn%2Finstall_idea_standard_modified_sessions.webp?alt=media&amp;token=bead71ca-fbcc-427f-a8ed-a2d3cf3aa21e" alt=""><figcaption><p>Increased the number of allowed sessions and added c6i and r6i</p></figcaption></figure>

4 - Reload the installer configuration

Go back to your IDEA installer and choose "Reload Changes"

<figure><img src="https://4178558898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff38qThSa0Aa40txosxbS%2Fuploads%2F9biuhLZaxKFYGqAOtZyp%2Finstall_idea_standard_reload_changes.webp?alt=media&amp;token=21b99cb7-002f-44f1-a412-829607f970b2" alt=""><figcaption><p>Reload the configuration after making your changes</p></figcaption></figure>

5 - Validate the installer will now use your new parameter(s)

Reloading configuration should take less than 5 seconds. Once done, validate your parameter(s) is/are have been successfully updated. The screen below confirm "vdc.dcv\_session.allowed\_sessions\_per\_user" and "vdc.dcv\_session.instance\_types.allow" have been correctly updated with my changes.

<figure><img src="https://4178558898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff38qThSa0Aa40txosxbS%2Fuploads%2FCHPwIndwHJH8Jpk9OQLv%2Finstall_idea_standard_configuration.webp?alt=media&amp;token=6c82d874-9e87-4f00-b0bf-6db2b2634625" alt=""><figcaption><p>IDEA will now configure the environment with your changes</p></figcaption></figure>

6 - Continue the installation

You can now move forward with the installer by choosing "Yes".

{% hint style="info" %}
IDEA parameters always use the same syntax: module.section.key.

Example:

If you want to update **scheduler.ec2.enable\_detailed\_monitoring,** you will have to edit \`\` \~/.idea/clusters/\<YOUR\_CLUSTER\_NAME>/\<YOUR\_REGION>/config/**scheduler**/settings.yml and find `enable_detailed_monitoring` key within the `ec2` section.
{% endhint %}

You can also change these settings post-installation. Refer to [Cluster operations](https://docs.idea-hpc.com/first-time-users/cluster-operations.md)for more details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.idea-hpc.com/first-time-users/install-idea/standard-installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
