# Run from Identity Apps

## ⚠️ Read this first

1. The root of the App Extensions repository  will be referred to `<APP_EXTENSIONS_HOME>` throughout this document.

2. The root of the Identity Apps repository  will be referred to `<IDENTITY_APPS_HOME>` throughout this document.

3. `<APP>` will mean either `console` or `myaccount`.

## Install Asgardeo specific Dependencies.

There are several dependencies that we are using only for Asgardeo specific use-cases (Analytics etc.).

### Locate and copy the scripts.

The pre-install could be found at `<APP_EXTENSIONS_HOME>/script-extensions/pre-install.js`.

Copy this to the following locations.

- `<IDENTITY_APPS_HOME>/apps/<APP>/scripts`

> **Note**
> `pre-install.js` script is a common script that goes into both `My Account` and `Console`.

### Install the dependencies

```bash
# From inside `<IDENTITY_APPS_HOME>`.
pnpm --filter @wso2is/console --filter @wso2is/myaccount exec node scripts/pre-install.js
```

## Merge the extensions folder

By default, `identity-apps` has the default extensions configurations that then gets overridden in the `app-extensions` build.

Since we are trying to manually do the process, we need to copy and merge the `extensions` folder in to the respective apps.

Copy and merge the `<APP_EXTENSIONS_HOME>/app-extensions/<APP>/src/extensions` folder in to the following locations.

- `<IDENTITY_APPS_HOME>/apps/<APP>/src/extensions`

> **Warning**
> The copy and merge operation should replace the duplicate files whilst preserving the other files.

## Add the `Asgardeo` theme

For Asgardeo, we have written a sub-theme based off of the `default` theme shipped in `identity-apps`. We need to copy it to the source.

Copy the `<APP_EXTENSIONS_HOME>/theme-extensions/asgardio` in to the following location.

- `<IDENTITY_APPS_HOME>/modules/theme/src/themes`

## Build the `Asgardeo` theme

Now we need to build the newly added Asgardeo theme.

```bash
cd modules/theme
pnpm build:dev
```

## Modify the `.env.local` file.

To start the the apps in port `443` pointing to the DEV backend, change the following in the `env.local` file located at `<IDENTITY_APPS_HOME>/identity-apps/apps/<APP>/.env.local`.

```shell
DEV_SERVER_PORT=443
DISABLE_DEV_SERVER_HOST_CHECK=true
```

## Changing the Deployment Configurations

Copy the `deployment.config.json` from `<APP_EXTENSIONS_HOME>/app-extensions/<APP>/src/public/deployment.config.json` to `<IDENTITY_APPS_HOME>/apps/<APP>/src/public` and change/verify the following configurations.

### `appBaseName`

Verify if the `appBaseName` is set to `""`.

```json
{
    "appBaseName": "",
}
```

### `serverOrigin`

URL added here will depend on the environment you wish to point. In this case dev cloud. (https://dev.api.asgardeo.io)

```json
{
    "idpConfigs": {
        "serverOrigin": "https://dev.api.asgardeo.io",
    },
    "serverOrigin": "https://dev.api.asgardeo.io",
}
```

### `idpConfigs`

Update the `authorizeEndpointURL`, `logoutEndpointURL`, etc. accordingly.

> :bulb: Skipping this step will result in unexpected session persistence issue.

#### Console

```json
{
    "idpConfigs": {
        "authorizeEndpointURL": "${serverOrigin}/${tenantPrefix}/${superTenantDomain}/oauth2/authorize?ut=${userTenantDomain}",
        "logoutEndpointURL": "${serverOrigin}/${tenantPrefix}/${superTenantDomain}/oidc/logout",
        "oidcSessionIFrameEndpointURL": "${serverOrigin}/${tenantPrefix}/${superTenantDomain}/oidc/checksession"
    }
}
```

#### My Account

```json
{
    "idpConfigs": {
        "authorizeEndpointURL": "${serverOrigin}/${tenantPrefix}/${userTenantDomain}/common/oauth2/authorize",
        "logoutEndpointURL": "${serverOrigin}/${tenantPrefix}/${userTenantDomain}/common/oidc/logout",
        "oidcSessionIFrameEndpointURL": "${serverOrigin}/${tenantPrefix}/${userTenantDomain}/common/oidc/checksession"
    }
}
```

### `superTenantProxy`

Add super tenant proxy.

> :bulb: With the tenant wise cookie handling, super tenant login flows have tenant path as /t/carbon.super. `superTenantProxy` is used to mask `carbon.super`.

```json
{
    "superTenantProxy" : "a",
}
```

### `extensions`

Add extension configs.

#### Console

```json
{
    "extensions": {
        "applicationInsightsEnabled": false,
        "applicationInsightsCookieDomain": "",
        "applicationInsightsCookiePostfix": "",
        "applicationInsightsInstrumentationKey": "",
        "applicationInsightsProxyEndpoint": "",
        "collaboratorUsernameRegex": "^[\\u00C0-\\u00FFa-zA-Z0-9.\\-_]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,10}$",
        "feedbackEndPoint": "https://dev.portal.asgardeo.io/api/cloud/v1/feedback/"
    }
}
```

#### My Account

```json
{
    "extensions": {
        "applicationInsightsEnabled": false,
        "applicationInsightsCookieDomain": "",
        "applicationInsightsCookiePostfix": "",
        "applicationInsightsInstrumentationKey": "",
        "applicationInsightsProxyEndpoint": ""
    }
}
```

### `theme`

Verify whether the theme is set to `asgardio`.

```json
{
    ...,
    "ui": {
        ...,
        "theme": {
            "name": "asgardio"
        }
    }
}
```

> :bulb: Read more about these configs [here](https://github.com/wso2/identity-apps/blob/master/docs/CONFIGURATION.md).

### Verify the Index

Do the following path changes in the `index.html`.

#### Stylesheets

Change `default` to `asgardio` and remove `<%= htmlWebpackPlugin.options.themeHash %>`.

```html
    <link href="<%= htmlWebpackPlugin.options.publicPath %>libs/themes/asgardio/theme.min.css" rel="stylesheet" type="text/css"/>

```

#### Favicon

Change `default` to `asgardio`.

```html
    <link rel="shortcut icon" href="<%= htmlWebpackPlugin.options.publicPath %>libs/themes/asgardio/assets/images/branding/favicon.ico" />
```

## Update Host Mappings

Add a the following mapping in your host file.

```dotenv
# Maps localhost to develeopment cloud's console host.
127.0.0.1 dev.console.asgardeo.io
```

> :bulb: In macOS, usually host file is located at `/private/etc/hosts`.

## Start

Now that the configurations are done with, we can go ahead and start the server.

> **Note**
>  You might need to use `sudo` here on UNIX systems since we are trying to use a privileged port less than `1024`.

```shell
# From `<IDENTITY_APPS_HOME>/apps/<APP>`
pnpm start
```

Once the dev server is up and running, navigate to [https://dev.console.asgardeo.io](https://dev.console.asgardeo.io) from your browser.

## Bypass the Certificate warning

If you get an invalid certificate warning and don't see a button to bypass, try typing `thisisunsafe` at the window (Only works in Chrome).
