# Run identity apps against the local setup

## ⚠️ 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`.

## Prerequisites

1. Follow the [Build Guide](https://github.com/wso2/identity-apps#build) and build the `<IDENTITY_APPS_HOME>` repo.

2. Start the [Asgardeo Local Setup](https://github.com/wso2-enterprise/asgardeo-product/tree/master/local).

## 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

Run the following command from inside `<IDENTITY_APPS_HOME>`

```bash
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
```

## 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 local setup backend. (https://api.asg.io)

```json
{
    "idpConfigs": {
        "serverOrigin": "https://api.asg.io",
    },
    "serverOrigin": "https://api.asg.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).

### Callback paths

Update the callback path related configs as follows.

```json
{
    "loginCallbackPath": "/login",
    "logoutCallbackPath": "/logout",
}
```

```json
{
    "routePaths": {
        "home": "/getting-started",
        "login": "/login",
        "logout": "/logout"
    },
}
```

### 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" />
```

## 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 server is up and running, navigate to the following URLs from your browser, depending on the app you are accessing.

- Console - [https://localhost:9001](https://localhost:9001)
- My Account - [https://localhost:9000](https://localhost:9000)

## 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).
