---
# System prepended metadata

title: HKLand Agent Platform App

---

HongkongLand workshop cheatsheet

#### Setup WSL (if applicable)
Doc Link:
- (This is enough)Install wsl and setup Ubuntu: https://docs.microsoft.com/zh-tw/windows/wsl/setup/environment#set-up-your-linux-username-and-password
- Install wsl more detail: https://docs.microsoft.com/zh-tw/windows/wsl/install

Require: Windows 10 2004 版和更高版本 
- Open Powershell
- Run `wsl --install`
_If get error “要求的作業需要提升的權限”_
_Fix: Run start-process powershell -verb runas, will open new powershelgl windows run as admin _
_If already install wsl but the version of Ubuntu is incorrect(or use other linux), run wsl --install -d Ubuntu-20.04_
- Restart the device
- Bash should popup with install ubuntu
- Set username and password
- Run `sudo apt update && sudo apt upgrade`

#### Setup Docker (if applicable)
- https://docs.docker.com/desktop/windows/wsl/#download

#### Setup VS Code (if applicable)
- https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode#install-vs-code-and-the-remote-wsl-extension
- Besure the remote extension is also downloaded
- Open up vscode with terminal by the command `code .`

#### Note for setup backend and portal
- Pull the project from remote (https)

- prerequisite
  - Install dotnet
``` 
#  Install dotnet
wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update; \
sudo apt-get install -y apt-transport-https && \
sudo apt-get update && \
sudo apt-get install -y  dotnet-sdk-5.0 dotnet-sdk-3.1 \
```

- helpful GUI tools
  - Azure Data Studio (for MsSQL Server, app database), ref: https://docs.microsoft.com/zh-tw/sql/azure-data-studio/download-azure-data-studio?view=sql-server-ver15
  - pgAdmin (for postgresql, authgear database), ref: https://www.pgadmin.org/download/pgadmin-4-windows/

##### Config wsl (bash)
    
- add configuration to `/etc/hosts`

```
127.0.0.1 local.hkland.com
127.0.0.1 auth.local.hkland.com
```
  - add /etc/wsl.conf // to avoid re-generate the `/etc/hosts` every time reboot the wsl 
```
[network] 
generateHosts = false
```
       
##### Config windows
    
- add configuration to `C:\WINDOWS\system32\drivers\etc\hosts`

```
127.0.0.1 local.hkland.com
127.0.0.1 auth.local.hkland.com
```
  - restart lxssManager, refs: https://www.how2shout.com/how-to/how-to-reboot-wsl-windows-subsystem-linux-in-windows-10.html
    - win+R -> service.msc -> lxssManager -> restart
  - re-setup the docker connection
    - settings -> resource -> wsl integration
  - cmd -> `ipconfig /flushdns`

##### Setup lms-db
 - `make lmsdb-init`
 - **potential problem** -> tar (permission denied)
  - `sudo chmod -R o+rwx $PATH`

##### Restore dotnet tools before going further
 - `make vendor`

##### Run database migration
  - `make db-migrate-up`
  - **potential problem** -> dotnet command not found -> Install dotnet as above mentioned
  - **potential problem** -> framework compatibale issue -> both `5.0` and `3.1` is required as above mentioned

##### Seed database
 - `make db-seed`

##### Connect to local database client
 - open `Azure Data Studio`
 - SQL login

##### Run the application
- `make dev`
- AZURE_NOTIFICATION_HUB_CONN_SHARED_ACCESS_KEY J7c33OSNxwH1MJ7V5ICh7V30gwmbOEg2JsM04+H6A2M=
- visit `local.hkland.com/admin` 

##### Run database migration for authgear db
 - `make authgear-migrate-up`

##### Connect to authgear database client
 - open `pgAdmin`
 - SQL login
 - **potential problem** -> master key setting is required, do not skip


--------------------------------------------------------------------------------
#### Setup Android Studio (if applicable)
- https://developer.android.com/studio/install

#### Note for setup app
- **potential problem** -> renew node version, ref: https://askubuntu.com/questions/1265813/how-to-update-node-js-to-the-long-term-support-version-on-ubuntu-20-04
- yarn
- setup react native environment, ref: https://gist.github.com/bergmannjg/461958db03c6ae41a66d264ae6504ade#connect-to-android-virtual-device-in-windows
    - check if missing any in `Install tools in WSL2` section of the above link; if yes, follow the given link for installation
        - **potential problem** -> beware of PATH specified in ~/.bash_profile (the condition will vary based on the Android SDK directory)
    - Open a emulator (via cmd or device manager)
    - Start adb server in Windows, refs: https://gist.github.com/bergmannjg/461958db03c6ae41a66d264ae6504ade#start-adb-server-in-windows
        - **potential problem** -> the adb cli can only be accessed in `adb.exe` dir, e.g. `\Android\Sdk\platform-tools`
    - follow `Connect to android virtual device in Windows`
    - use `socat` instead of env vars for smoother dev experience
    - check `adb devices` in app project directory to see if the network forwarding is succeeded


- check and follow the app setup guide `app/readme.md`

- since there is not gpg setup currently, so we need to manually copy `android/app/src/local/google-services.json` for developing

- tips
`adb shell input keyevent 82` to reload before metro bundler is connected
`crl+shift+esc` kill the adb server if needed
a



https://linuxize.com/post/how-to-install-yarn-on-ubuntu-20-04/


- install Android SDK
```
sudo apt-get update
cd
sudo apt-get install unzip zip
wget https://dl.google.com/android/repository/sdk-tools-linux-4333796.zip
unzip sdk-tools-linux-4333796.zip -d Android
rm sdk-tools-linux-4333796.zip
sudo apt-get install -y lib32z1 openjdk-8-jdk
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
export PATH=$PATH:$JAVA_HOME/bin
printf "\n\nexport JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64\nexport PATH=\$PATH:\$JAVA_HOME/bin" >> ~/.bashrc
cd Android/tools/bin
### check latest platform and build-tools versions (29, 29.0.2)
./sdkmanager --install "platform-tools" "platforms;android-29" "build-tools;29.0.2"
export ANDROID_HOME=~/Android
export PATH=$ANDROID_HOME/tools:$PATH
export PATH=$ANDROID_HOME/tools/bin:$PATH
export PATH=$ANDROID_HOME/platform-tools:$PATH
printf "\n\nexport ANDROID_HOME=~/Android\nexport PATH=\$PATH:\$ANDROID_HOME/tools\nexport PATH=\$PATH:\$ANDROID_HOME/platform-tools" >> ~/.bashrc
./sdkmanager --update
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
### check latest grade version
sdk install gradle 5.5.1
gradle -v

### run "adb start-server" in powershell
```

```
cat ~/.bash_profile 
```


------------------------------------------------------------------
# HKLand Agent Platform App

## Requirements

- node 12.5.1
- Xcode 11.6
  - Xcode with under 11.6 will encounter the issue below with react-native 0.63.3
    > refs: https://github.com/facebook/react-native/issues/30231


## Initialize
```sh
$ make setup
```
- manually copy the value `AZURE_NOTIFICATION_HUB_CONN_SHARED_ACCESS_KEY` in `server/secret.txt` after file decryption to the corresponding key in `server/.env` for PN services

## Quick starts

### iOS

```sh
$ yarn
$ yarn run ios
```

- Caveat: `Flipper SDK` is updated from `react native 0.63.2` to `react native 0.63.3`, so if you encounter the Flipper SDK version incompatible error, please run the following for updating your local podspec references before `yarn run ios`:

```sh
$ cd ios
$ pod repo update
$ yarn run ios
```

### Android

**Note that we need to do some extra works for the emulator connecting to the `localhost`:**

- install `adb` (prerequisite: `homebrew`, or you could find other ways to install it. See: https://stackoverflow.com/questions/31374085/installing-adb-on-macos)

```sh
$ brew cask install android-platform-tools
```

- check if `adb` is successfully downloaded

```sh
$ adb devices
```

#### run in emulator

- Note that `localhost` is not working on Android, so slight changes are need for env variables

- change the host of urls in `.env` to `10.0.2.2` when developing with emulator
  - update the `SERVER_ENDPOINT` in app/.env to `http://10.0.2.2`
  - update the `AUTHGEAR_ENDPOINT` in app/.env to `http://10.0.2.2:3030`

#### run in real devices

- change the host of urls in `.env` to your ip address when developing with real devices
  - update the `SERVER_ENDPOINT` in app/.env to `http://${YOUR_IP_ADDRESS}`
  - update the `AUTHGEAR_ENDPOINT` in app/.env to `http://${YOUR_IP_ADDRESS}:3030`

- how to get your ip address?
  - macOS, `ifconfig` -> get the inet of `en0`
  - windows, wsl, `ipconfig` (in cmd) -> get the one under `Wireless LAN adapter Wi-Fi` -> `IPv4 Address`


- lastly

  - windows, `wsl`
  ```sh
  # force listening 127.0.0.1, refs: https://gist.github.com/bergmannjg/461958db03c6ae41a66d264ae6504ade#build-app-in-wsl2
  $ yarn start --host 127.0.0.1 
  $ yarn run android
  ```

  - macOS
  ```sh
  $ yarn start
  $ yarn run android
  ```


## E2E Test

- ios

```sh
yarn test-e2e-ios
```

- android
  - need to replace `avdName` in `package.json` with the emulator name you have in local

```sh
yarn test-e2e-android
```



https://linuxize.com/post/how-to-install-yarn-on-ubuntu-20-04/




- app/android/app/src/local/google-services.json
```
{
  "project_info": {
    "project_number": "80271025136",
    "project_id": "hkland-agent-platform-debug",
    "storage_bucket": "hkland-agent-platform-debug.appspot.com"
  },
  "client": [
    {
      "client_info": {
        "mobilesdk_app_id": "1:80271025136:android:92b0309a96a9f4c4883335",
        "android_client_info": {
          "package_name": "com.oursky.hklagent.debug"
        }
      },
      "oauth_client": [
        {
          "client_id": "80271025136-57p7nhrsij42jmtru7a7alinv7hdtloi.apps.googleusercontent.com",
          "client_type": 3
        }
      ],
      "api_key": [
        {
          "current_key": "AIzaSyD_pG_xugewqdS4RyTTPQ1CMJNBax7sAS4"
        }
      ],
      "services": {
        "appinvite_service": {
          "other_platform_oauth_client": [
            {
              "client_id": "80271025136-57p7nhrsij42jmtru7a7alinv7hdtloi.apps.googleusercontent.com",
              "client_type": 3
            }
          ]
        }
      }
    }
  ],
  "configuration_version": "1"
}
```