In order to build and deploy MLSpace to your AWS account you will need the following software installed on your machine:

• git
• awscli
• nodejs 18+
• docker or a compatible runtime for generating lambda layers
• cdk (npm install -g cdk)

In addition to the required software you will also need to have the following information:

• AWS account Id and region you'll be deploying MLSpace into (you'll need admin credentials or similar)
• IdP information including the OIDC endpoint and client name

There are two options for configuring MLSpace for deployment:

Configure MLSpace using Option 1 if:

• you want to be prompted for only the settings necessary to launch MLSpace with minimal configuration changes; or...
• you want to be prompted only for the necessary settings as well as values that are commonly modified (VPC configuration, IAM roles, etc)
• you want to configure and deploy MLSpace with a generated config file which is not committed to git

After running the MLSpace Config Wizard, a new file will be generated: /lib/config.json.

When MLSpace is deployed it will merge the settings in /lib/config.json and constants.ts to determine the final configuration settings (giving precedence to values set in /lib/config.json).

Any values left empty while using the MLSpace Config Wizard will default to what is set in the lib/constants.ts file.

The MLSpace Config Wizard can be invoked with the command:

npm run config

This will prompt you to choose between Basic Config and Advanced Config.

• Basic Config - only prompts for the properties which must be set in order to deploy MLSpace.
• Advanced Config - prompts for required fields as well as optional configurations which are commonly customized.

If selecting Basic Config, the properties you will be prompted for are:

• AWS account ID: the AWS account ID for the account MLSpace will be deployed into
• AWS region: the region that MLSpace resources will be deployed into
• OIDC URL: the OIDC endpoint that will be used for MLSpace authentication
• OIDC Client Name: the OIDC client name that should be used by MLSpace for authentication

If selecting Advanced Config you will be prompted for the same properties Basic Config prompts for, as well as other optional values. Anything not specified will use the defaults in constants.ts and/or provisioned by MLSpace.

The Advanced Config will ask:

Do you want to use existing VPC? If you answered yes you will be prompted for:

• VPC Name: if MLSpace is being deployed into an existing VPC this should be the name of that VPC
• VPC ID: if MLSpace is being deployed into an existing VPC this should be the ID of that VPC
• VPC Default Security Group: if MLSpace is being deployed into an existing VPC this should be the default security group of that VPC

Do you want to use existing IAM Roles? If you answered yes you will be prompted for:

• S3 Reader Role ARN: ARN of an existing IAM role to use for reading from the static website S3 bucket
• Bucket Deployment Role ARN: ARN of an existing IAM role to use for deploying to the static website S3 bucket
• Notebook Role ARN: ARN of an existing IAM role to associate with all notebooks created in MLSpace
• App Role ARN: ARN of an existing IAM role to use for executing the MLSpace lambdas
• EMR Default Role ARN: ARN of an existing IAM role that will be used as the 'ServiceRole' for all EMR clusters
• EMR EC2 Instance Role ARN: ARN of an existing role that will be used as the 'JobFlowRole' and 'AutoScalingRole' for all EMR clusters

Do you want to modify the banner displayed on MLSpace? If you answered yes you will be prompted for:

• System Banner Text: the text to display on the system banner displayed at the top and bottom of the MLSpace web application. If set to a blank string no banner will be displayed
• System Banner Background Color: the background color of the system banner if enabled
• System Banner Text Color: the color of the text displayed in the system banner if enabled

Configure MLSpace using Option 2 if:

• the MLSpace Config Wizard doesn't configure all of the settings you need to customize
• you wish to have your configuration changes in a file that's committed to git
• will have to resolve conflicts when upgrading MLSpace

If you are pre-creating roles you will need to ensure that the required role arns (APP_ROLE_ARN, NOTEBOOK_ROLE_ARN), role names (KEY_MANAGER_ROLE_NAME if EXISTING_KMS_MASTER_KEY_ARN is not set), and AWS_ACCOUNT (used to ensure unique S3 bucket names) have been properly set in lib/constants.ts.

You will also need to set OIDC_URL and OIDC_CLIENT_NAME with the correct values based on your chosen IdP. These property must be set prior to deploying MLSpace.

To see the full list of configurable properties and their descriptions, see the [Configurable deployment parameters section](Configurable deployment parameters).

Once configuration has been completed you will also need to create a production build of the web application. You can do this by changing to the web application directory (frontend/) and running:

# From project root directory
cd frontend
npm run clean && npm install

This will generate a production optimized build of the web application and documentation, the resulting artifacts will be written to the frontend/build/ directory.

There are no web application specific configuration parameters that need to be set as the configuration will be dynamically generated as part of the CDK deployment based on the variables set during the configuration steps, as well as the deployed resources.

The MLSpace application is a standard CDK application and can be deployed just as any CDK application is deployed:

# From project root directory
npm install && cdk bootstrap <REPLACE WITH YOUR ACCOUNT NUMBER>/<REPLACE WITH TARGET REGION>

Once the account has been bootstrap you can deploy the application. You can optionally include --require-approval never in the below command if you don't want to confirm changes:

# From project root directory
cdk deploy --all

If the config-helper doesn't provide the level of customization you need for your deployment, you can update the values in lib/constants.ts based on your specific deployment needs. Some of these will directly impact whether new resources are created within your account or whether existing resources (VPC, KMS, Roles, etc) will be leveraged.