docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/4_X(cross)_Development_System:_ Internals /3.4.4.2_xds-server/3.4.4.2.3_how-to-run.md

   1 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/devguides/master/xds-docs-guides-devguides-book.yml -->
   2 # How to run
   3
   4 `xds-server` has been designed to easily compile and debug
   5 [AGL](https://www.automotivelinux.org/) applications. That's why `xds-server` has
   6 been integrated into AGL SDK docker container.
   7
   8 >**Note:** For more info about AGL SDK docker container, please refer to
   9 [AGL SDK Quick Setup](../../../../../getting_started/reference/getting-started/docker-container-setup.html)
  10
  11 ## Start xds-server
  12
  13 There are several way to install xds-server and start-up depend of installation type:
  14
  15 | Installation type | Supported<br> host OS   | Start-up                                          | Install instructions |
  16 |-------------------|-------------------------|---------------------------------------------------|----------------------|
  17 | Docker container  | Linux or MacOS          | Automatic based on systemd user service           | [see Installation based on Docker container](../../part-1/server-part.html#docker-container) |
  18 | Virtual Machine   | Linux, MacOS or Windows | Automatic based on systemd user service           | [see Installation based on VirtualBox appliance](../../part-1/server-part.html#virtualbox-appliance) |
  19 | Native            | Linux                   | Automatic based on systemd user service or manual | [see Native installation](../../part-1/server-part.html#native) |
  20 | Native            | MacOS or Windows        | Manually                                          | [see Native installation](../../part-1/server-part.html#native) |
  21
  22 ### Automatic start-up based on systemd user service
  23
  24 XDS server is started as a user service by Systemd.
  25
  26 ```bash
  27 /usr/lib/systemd/user/xds-server.service
  28 ```
  29
  30 Use well-known systemd commands to control `xds-server.service` service.
  31
  32 ```bash
  33 # Enter in docker container or VM
  34 # (optional, depending on installation type)
  35 ssh -p 2222 devel@localhost
  36
  37 # Status XDS server:
  38 systemctl --user status xds-server
  39
  40 # Restart XDS server
  41 systemctl --user restart xds-server
  42 ```
  43
  44 If needed you can change default setting by defining specific environment
  45 variables file
  46
  47 ```bash
  48 ssh -t -p 2222 devel@localhost vim /etc/default/xds-server
  49 ```
  50
  51 For example to control log level, just set LOG_LEVEL env variable.
  52
  53 knowing that supported *level* are:
  54
  55 - panic
  56 - fatal
  57 - error
  58 - warn
  59 - info
  60 - debug
  61
  62 ```bash
  63 docker exec ${CONTAINER_NAME} bash -c "echo 'LOG_LEVEL=debug' >> /etc/default/xds-server"
  64 ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server"
  65 ```
  66
  67 ### Manual start-up
  68
  69 On **Linux or MacOS**, simply execute `xds-server` executable:
  70
  71 ```bash
  72 /opt/AGL/bin/xds-server
  73 ```
  74
  75 On **Windows**, simply execute `xds-server` executable:
  76
  77 ```batch
  78 C:\AGL\bin\xds-server.exe
  79 ```
  80
  81 <!-- section-note -->
  82 **Note:**
  83
  84 Invoke `xds-server --help` to get more details about possible options that allow
  85 for example to change logging level or select another configuration file.
  86
  87 <!-- end-section-note -->
  88
  89 ## XDS server REST API and Web application
  90
  91 `xds-server` exposes a REST API and serves a basic web-application.
  92
  93 REST API based url is `http://localhost:8000/api/v1/` when XDS server is
  94 running on your host (localhost) and basic web-application is available at
  95 `http://localhost:8000`.
  96
  97 Just replace `localhost` by the host name or ip when `xds-server` is running
  98 on another host.
  99
 100 ```bash
 101 # Get version using REST API
 102 curl http://localhost:8000/api/v1/version
 103
 104 # Open browser and local xds-server web-application
 105 xdg-open http://localhost:8000
 106 ```
 107
 108 Then follow instructions provided on this page to install and start `xds-agent`
 109 that must run locally on your machine.
 110
 111 See also [xds-agent documentation](../2_xds-agent/0_abstract.html) for more details.
 112
 113 ## SDK cross-toolchain Management
 114
 115 ### Setup to add support of a new SDK family
 116
 117 <!-- section-note -->
 118 **Optional step**: read this chapter only if you plan to add a new SDK family.
 119 <!-- end-section-note -->
 120
 121 `xds-server` dynamically detects supported SDKs by scanning sub-directories of
 122 `sdkScriptsDir` directory (see [Configuration chapter](2_config.html)).
 123
 124 Each sub-directory (usually name is the same as the SDK family) of `sdkScriptsDir`
 125 must contain a set of scripts that will be called by `xds-server` to managed SDKs
 126 of a specific family.
 127
 128 These scripts are:
 129
 130 - `add`: used to add/install a new SDK
 131 - `db-dump`: returned the list of available and installed SDKs (JSON format)
 132 - `db-update`: update SDKs database
 133 - `get-family-config`: returned SDK family configuration structure (JSON format)
 134 - `get-sdk-info`: extract SDK info (JSON format) from a SDK file/tarball
 135 - `remove`: used to remove an existing SDK
 136
 137 For example, here 2 SDKs family (`agl` and `zephyr`) are defined:
 138
 139 ```bash
 140 # > tree ./sdks/
 141 ./sdks/
 142 ├── agl
 143 │   ├── add
 144 │   ├── db-dump
 145 │   ├── db-update
 146 │   ├── get-family-config
 147 │   ├── get-sdk-info
 148 │   └── remove
 149 ├── README.md
 150 └── zephyr
 151     ├── add
 152     ├── db-dump
 153     ├── db-update
 154     ├── get-family-config
 155     ├── get-sdk-info
 156     └── remove
 157 ```
 158
 159 On startup `xds-server` will call in order:
 160
 161 - `sdks/*/get-family-config` to get configuration of each SDK family.
 162 - `sdks/*/db-update` to update database (only when `SdkDbUpdate` is set to ̀`startup`,
 163    see [Configuration chapter](2_config.html) for more details)
 164 - `sdks/*/db-dump` scripts to get the initial list of available and installed SDKs.
 165
 166 Please refer to `sdks/README.md` for more information about scripts definition
 167 and to understand how to add support of a new SDK family.
 168
 169 ### Install a new SDK
 170
 171 Please refer to [Installing AGL SDKs](../../part-1/install-sdk.html) chapter.
 172
 173 ### Un-install a SDK from command line
 174
 175 Used `sdks` command of `xds-cli` tool to managed SDKs.
 176
 177 ```bash
 178 # List installed SDKs
 179 xds-cli sdks ls
 180 List of installed SDKs:
 181   ID            NAME                                                            STATUS          VERSION         ARCH
 182   c39e5998      poky-agl_aarch64_4.0.1                                          Installed       4.0.1           aarch64
 183   d610bfbf      poky-agl-aarch64.current_on_iotbzh_download-3.99.1+snapshot     Installed       3.99.1+snapshot aarch64.current_on_iotbzh_download
 184   a0ae663d      poky-agl-corei7-64-3.99.1+snapshot                              Installed       3.99.1+snapshot corei7-64
 185   87f0400b      AGL-release-dab-3.99.3-m3ulcb-nogfx                             Installed       3.99.3          aarch64
 186   352c0584      poky-agl-corei7-64-3.99.2+snapshot                              Installed       3.99.2+snapshot corei7-64
 187   d65fe750      AGL-release-eel-latest-qemux86-64                               Installed       4.99.5          corei7-64
 188
 189 # Un-install a SDK
 190 xds-cli sdks uninstall d65fe750
 191 SDK ID d65fe750-d3a7-38f5-83d8-3d3806054f8d successfully deleted.
 192 ```
 193
 194 ### Un-install a SDK from XDS Dashboard
 195
 196 Open XDS-Dashboard in web-browser and select `SDKs` entry in left side menu.
 197
 198 If needed, switch to `BASIC SDKS VIEW` view and click on trash icon located
 199 in the top-right corner of SDK card.