# Development Locally

This guide is intended for the local development of apps based on the insureMO app framework and RainbowUI.

<div class="docs-note"><span class="docs-admonitions-text">note</span>

The App Framework provided in this documentation is exclusively designed for use within the specific application referenced herein. It is not intended for the development of new tenant applications. Any attempt to extend or modify the framework for use in other projects or environments is not recommended.Please ensure that the framework is only utilized for its intended purpose within the specified application.

</div>

## Config-Center properties for development ENV

Below config properties would be setup by SiteOps team while initialize the enviornment for development:

```bash
# the flag to enable localhost first routing, i.e. local debug
platform.loadBalancer.localHostFirstRule.enable=true

# the server side service instances related ip-address, please update the value if necessary
integration.server.address=172.25.*;10.*;172.28.*

# the local dev computer ip address, please add if necessary. concat with comma (;)
ebao.service.local-dev-address=172.*

# the config properties for http methods, please add the OPTIONS to enable CORS
httpAllowedMethods=GET,POST,OPTIONS

```

## Frontend UI Development Locally

Assume you're developing frontend UI application based on insureMO's RainbowUI framework.
If you want to debug both the UI and back-end app locally (**Local UI** > **Local Service**), see the steps below.

### Config local npm environment parameter

To access from the `public internet`, please use the settings below. For `internal staff`, please retain your current settings.

```shell
npm config set registry https://registry.npmjs.org/
npm config set @insuremo:registry=https://public.insuremo.com/artifactory/api/npm/npm/
npm config set always-auth false
```

You may use a mirror site to speedup package install. for example, npmnirror.com

```shell
npm config set registry https://registry.npmmirror.com/
npm config set @insuremo:registry=https://public.insuremo.com/artifactory/api/npm/npm/
npm config set always-auth false
```

Please check the content of your local .npmrc file(file path:C:\Users\username\) to verify the above config is correctly set.

If there is an error when executing npm command, please check whether your npm version meets the requirement.

### Adjust Configuration

Adjust the `config.json` file.

```json
{
  "UI_API_GATEWAY_PROXY": "https://tenantcode***.insuremo.com",
  "UI_LOGIN": false,
  "UI_CALL_KEYS": true,
  "UI_TENANT": "tenantcode",
  "UI_PRODUCT_FACTORY_AUTHORITY_FLAG": true,
  "LOCAL_PROXY_PATHS": [
    "/* appframework-bff-app   uncommet it when you want to invoke your local bff service */"
  ]
}

```

Replace the gateway proxy URL with your app's domain URL.

### Set Proxy

Set the proxy inside `webpack.dev.js`.

```json
devServer: {
    ...
    proxy: {
        '/appframework-bff-app': {// invoke the bff service on local machine. change the service name by yourself.
            target: '<http://localhost:80>',
            changeOrigin: true,
            pathRewrite: {'^/appframework-bff-app': ''}
        }
    }
},

```

## Service App Development Locally

### Maven Configuration

Set up Maven repository to pull required dependencies, including Spring Boot and related libraries.
  
To access from the `public internet`, please use the settings below. For `internal staff`, please retain your current settings.

```XML
<repositories>
    <repository>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>insuremo-public</id>
        <name>InsureMO Maven Repository</name>
        <url>https://public.insuremo.com/artifactory/maven/</url>
    </repository>
</repositories>

<pluginRepositories>
    <pluginRepository>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>insuremo-public</id>
        <name>InsureMO Maven Repository</name>
        <url>https://public.insuremo.com/artifactory/maven/</url>
    </pluginRepository>
</pluginRepositories>
```

### Configure in application-local.properties

**Add the following properties and application-local properties for local development.**

```bash
# disable in local dev as local is normally windows, but server side is linux
server.tomcat.accesslog.enabled=false
gc.log.purge.enable=false

# enable local API rewrite
ebao.service.local-dev.enabled=true

// if your API has EntityIdSign/Mask feature enabled, please add below config property
app.mask.enabled=true

// set below for global transaction when you do local debug
seata.defaultGlobalTransactionTimeout=600000
```

To verify whether you need to configure `app.mask.enabled=true`, please check the API payload. For details, see [Security](https://docs.insuremo.com/common/doc_00000058).

![Untitled](image/gateway_switch/Untitled%206.png)

### Local Service Startup Configuration

**Prepare personal access token to load insureMO Config Center properties.**

The application requires connecting to the **Config Center** to load initial config data when it runs locally. Therefore, you need to generate an access token to connect to the **Config Center**.

The token should match the environment corresponding to the `insuremo_gw_url`.

Follow the steps below:

1. Log in to the [insureMO Portal](https://portal.insuremo.com/) and access **My Console**.
2. Click **Application** > **All Services** to enter your application details.
3. Locate your runtime environment tag.
4. In the tenant section, find listed personal access tokens. You can view and use any of them.
5. If you want to create a new token, click **Generate key** to generate a token.
6. Save the token for later use.

<div class="docs-note"><span class="docs-admonitions-text">note</span>

 DO NOT delete tokens created by others.

</div>

If you're working on an existing project, you can either ask your TS to provide the token for local development, or just use the token setting for the insureMO Pod as follows.

1. Find the pod hosting in the insureMO development (sandbox) environment, and click **View**.

    ![image1.png](image/gateway_switch/image1.png)

2. Search for `insuremo_access_token` inside the pod information view.

    ![image2.png](image/gateway_switch/image2.png)

**Add environment variables for local application running.**

```bash
insuremo_gw_url=https://tenantcode***.insuremo.com
insuremo_access_token=Bearer ****
spring.profiles.active=local
TENANT_CODE=tenantcode

```

To configure the above environment variables, the process may vary depending on your IDE (e.g. IntelliJ IDEA, Eclipse) and operating system (e.g. Windows, MacOS). Alternatively, you can set these parameters as VM options:

```bash
-Dinsuremo_access_token="Bearer ****" -Dinsuremo_gw_url=https://tenantcode***.insuremo.com -Dspring.profiles.active=local -DTENANT_CODE=trialzone6
```

</div> note
If your service is based on JDK 17, you need to add additional JVM parameters or environment variables when starting it.

```bash
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.io=ALL-UNNAMED
--add-opens java.base/java.lang.reflect=ALL-UNNAMED
--add-opens java.base/java.time=ALL-UNNAMED
--add-opens java.base/java.util=ALL-UNNAMED
--add-opens java.base/java.nio=ALL-UNNAMED
--add-opens java.sql/java.sql=ALL-UNNAMED
--add-opens java.base/java.math=ALL-UNNAMED
--add-opens java.base/java.net=ALL-UNNAMED
--add-opens java.base/java.util.concurrent=ALL-UNNAMED
--add-opens java.base/sun.nio.ch=ALL-UNNAMED
--add-opens java.base/sun.net.www.protocol.http=ALL-UNNAMED
--add-opens java.xml/com.sun.org.apache.xerces.internal.parsers=ALL-UNNAMED
--add-opens jdk.unsupported/sun.misc=ALL-UNNAMED
```

</div>

### Debug Locally

You can access the localhost service directly as follows.

![Untitled](image/gateway_switch/Untitled%207.png)

#### Call API through application domain and route to local service

If you're developing within **insureMO’s network**, such as a VM, you can still access the API through **the app domain**, which will automatically route to your local service.

This routing is determined by the client IP address from the request. However, if a **proxy (WAF)** is involved, the detected IP may be incorrect.

</div> note

To verify the client IP address detected from an API call, adjust the logging level of **server.request.response.logging** to debug in your service’s **boot-admin**, then check the **x-real-ip** in the logs.

</div>

For instance, if the app domain is accessible from the public Internet (through proxy / WAF), your client IP address will differ from your local IP address. In such cases, you’ll need to configure a local DNS entry in your host file:

```bash
# replace the app-env-domain with your app domain, and the 172.25.12.151 is fixed.
# example:
# 172.25.12.151 TenantCode-gi-ptdev.insuremo.com
172.25.12.151 app-env-domain
```

You can also pass a header to specify your local IP, allowing the request routing to your local development service. Either one of the following headers is available.

- `x-mo-original-client-ip: 172.30.3.100`

Please kindly remember to replace `172.30.3.100` with your local IP address.

![Untitled](image/gateway_switch/Untitled%208.png)

## Troubleshooting

### No such host is known

In your local development env, you can disable the tracing collector by setting below configure either in application-local.properties or in VM options:

```java
otel.tracing.enabled=false
```

### Don't want to connect to RabbitMQ

In your local development env, if you're not using RabbitMQ for application message, you can disable the RabbitMQ auto-configuration by setting below configure either in application-local.properties or in VM options:

```java
mq.disabled=true
```

### Check Spring Boot Admin

In the standard insureMO deployment, each tenant-app-domain will possess a boot-admin. To access it, you need to log in to the UI/admin first, then switch the URL to the boot-admin.

For example, if your tenant is **trialzone6** and you need to access boot-admin in the environment, see the steps as follows.

1. Log in to UI Admin: `https://{tenantcode}-{env}.insuremo.com/ui/admin/#/`
2. Switch to boot-admin: `https://{tenantcode}-{env}.insuremo.com/boot-admin/`
3. Log in to boot-admin with username and password, default by **admin/admin**.

![Untitled](image/gateway_switch/Untitled%209.png)

If you encounter **token error** as shown in the image and have confirmed your login, take one of the following options:

- Clear the browser cache and re-login, then switch to boot-admin.
- Open the developer tool, check the Cookies, and remove the **auth_code** that is not associated with the current tenant domain.

  ![Untitled](image/gateway_switch/Untitled%2010.png)

  ![Untitled](image/gateway_switch/Untitled%2011.png)

You can enable the debug log in boot-admin for the service app and check logs within the monitor. Some commonly used loggers include:

- **server.request.response.logging**
- **remoteCall.request.response.logging**
- **com.ebao.unicorn.platform.app.dev.LocalhostFirstInterceptorFilter**

Additionally, you can verify the local service instance in boot-admin's environment section, specifically searching for the IP address.

![Untitled](image/gateway_switch/Untitled%2012.png)

For further usage of Spring Boot, see [Spring Boot Admin](https://docs.insuremo.com/common/doc_00000370).

### Check Logs and Trace in Monitor

See the following image for efficiently checking the logs and trace in the monitor.

![Untitled](image/gateway_switch/Untitled%2013.png)
