docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/1_Installing_XDS /3.4.1.1_Server_Part.md

   1 # Server Part
   2
   3 Depending on your situation, you must either install the
   4 XDS server part or you can skip installation:
   5
   6 - If you are a developer and plan to connect to and use an existing `xds-server`
   7   that is running on your local network (On-Premise) or is available from
   8   the Cloud (SaaS), you do not need to install the server part.
   9 - If you are configured for Standalone or you are an administrator
  10   that wants to install an On-Premise solution, you must install
  11   the server part.
  12
  13 This section describes three types of server part installations:
  14
  15 | Install type | Supported OS | Section to refer |
  16 |--------------|--------------|------------------|
  17 | Container | Linux or MacOS | [Docker Container](#docker-container) |
  18 | Virtual Machine | Linux, MacOS or Windows | [VirtualBox Appliance](#virtualbox-appliance) |
  19 | Native | Linux | [Native](#native) |
  20
  21 ## Docker Container
  22
  23 This section describes how to install the server part (`xds-server`)
  24 into a
  25 [Docker Container](https://www.docker.com/resources/what-container)
  26 on a Linux-based system or a MacOS system.
  27
  28 ### Prerequisites
  29
  30 The system on which you are installing the server part
  31 must meet both the following prerequisites:
  32
  33 - You must have Docker installed on the host machine.
  34   For information on installing Docker, see the
  35   [Docker documentation](https://docs.docker.com/engine/installation/).
  36
  37 - Aside from having Docker installed, users must be part of a
  38   docker
  39   [group](https://www.linux.com/learn/intro-to-linux/2017/12/how-manage-users-groups-linux).
  40   Enter the following command to display the system's groups and
  41   then search for and list the Docker groups:
  42
  43   ```bash
  44   groups | grep docker
  45   ```
  46
  47   If the users that plan on using the container are not part of the
  48   Docker group or the group does not exist, you must take steps.
  49   See the [docker post install instructions](https://docs.docker.com/install/linux/linux-postinstall/)
  50   for details on creating a Docker group and adding users.
  51
  52   Following is a summary of the key commands:
  53
  54   ```bash
  55   sudo groupadd docker
  56   sudo usermod -aG docker $USER
  57   # Log out and re-login so the system can re-evaluate the group membership
  58   # You might also need to start docker service manually
  59
  60   sudo service docker start
  61   # or
  62   sudo systemctl start docker
  63   ```
  64
  65 ### Get the Container
  66
  67 Use the following command to load the pre-built AGL
  68 SDK Docker image, which includes `xds-server`:
  69
  70 ```bash
  71 wget -O - http://iot.bzh/download/public/XDS/docker/docker_agl_worker-xds-latest.tar.xz | docker load
  72 ```
  73
  74 The following command lists and displays information about the image:
  75
  76 ```bash
  77 docker images "docker.automotivelinux.org/agl/worker-xds*"
  78
  79 REPOSITORY                                  TAG                 IMAGE ID            CREATED             SIZE
  80 docker.automotivelinux.org/agl/worker-xds   5.0                 877979e534ff        3 hours ago         106MB
  81 ```
  82
  83 ### Create and Start a New Container
  84
  85 Running the following script creates a new Docker image and starts a new container:
  86
  87 ```bash
  88 # Get script
  89 wget -O xds-docker-create-container.sh 'https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-server.git;a=blob_plain;f=scripts/xds-docker-create-container.sh;hb=master'
  90
  91 # Create new XDS worker container (change the -id option value if you get a port conflict error)
  92 bash ./xds-docker-create-container.sh -id 0
  93
  94 # Be sure the new container is running
  95 docker ps | grep worker-xds
  96 f67079db4339        docker.automotivelinux.org/agl/worker-xds:5.0   "/usr/bin/wait_for..."   About a minute ago   Up 34 seconds       0.0.0.0:8000->8000/tcp,0.0.0.0:10809->10809/tcp, 0.0.0.0:2222->22/tcp   agl-xds-HOSTNAME-0-USERNAME
  97 ```
  98
  99 In the previous example, the container exposes following ports:
 100
 101 | Port number | Description                                 |
 102 |-------------|---------------------------------------------|
 103 |     8000    | `xds-server`: serve XDS webapp and REST API |
 104 |     2222    | ssh                                         |
 105
 106 This container also creates the following volumes, which are shared folders between
 107 inside and outside Docker:
 108
 109 | Directory on host | Directory inside docker | Comment |
 110 |-------------------|-------------------------|---------|
 111 | $HOME/xds-workspace | /home/devel/xds-workspace | XDS projects workspace location|
 112 | $HOME/xds-workspace/.xdt_0 | /xdt | location to store SDKs |
 113 | $USER_VOLUME | $USER_VOLUME | user path, see `--volume` option of `xds-docker-create-container.sh` script |
 114
 115 #### Optional Settings
 116
 117 When you create the container, you can use optional settings.
 118 This section shows minimal settings to configure the container.
 119 For more detailed `xds-server` configuration information including settings, see the
 120 "[xds-server configuration](../part-2/1_xds-server/2_config.html)" section.
 121
 122 - **`--volume`**
 123
 124   Adds a new shared directory using the `--volume` option (e.g.
 125   used with Path-Mapping folder types):
 126
 127   ```bash
 128   # Create new XDS worker container and share extra '$HOME/my-workspace' directory
 129   bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME/my-workspace
 130   ```
 131
 132 - **`--id`**
 133
 134   Changes the port used by Docker:
 135
 136   ```bash
 137   # Create new XDS worker container with a different port number
 138   ID=3
 139   bash ./xds-docker-create-container.sh -id ${ID}
 140
 141   # Check that new container is running (in example below id has been set to 3)
 142   docker ps | grep worker-xds
 143   f67079db4339        docker.automotivelinux.org/agl/worker-xds:5.0   "/usr/bin/wait_for..."   About a   minute ago   Up 34 seconds       0.0.0.0:2225->22/tcp, 0.0.0.0:8003->8000/tcp, 0.0.0.0:10892->10809/tcp   agl-xds-3
 144   ```
 145
 146   <!-- section-note -->
 147   **WARNING:**
 148   Changing the container id impacts the port number used to connect to `xds-server`.
 149   Consequently, you might need to adjust the `xds-agent` configuration in order
 150   to match the correct port number.
 151
 152   In the previous example where the container id is set to "3", the export
 153   port number is `8003`.
 154   In this case, you must define "url" in the `xds-server` configuration as follows:
 155
 156   ```json
 157   {
 158       ...
 159       "xdsServers": [
 160         {
 161           "url": "http://localhost:8003"
 162         }
 163       ],
 164       ...
 165   }
 166   ```
 167
 168   For more information, see the
 169   [xds-agent configuration](../part-2/2_xds-agent/2_config.html) section.
 170   <!-- end-section-note -->
 171
 172 #### Manually Setup the Docker User ID
 173
 174 If you are using path-mapping sharing type for your projects, you need to
 175 have the same user ID and group ID inside and outside Docker.
 176
 177 By default, user, password and group names inside Docker are `devel`, `devel` and `1664`, respectively.
 178
 179 <!-- section-note -->
 180 **NOTE:**
 181
 182 If you used the `xds-docker-create-container.sh` script to create the XDS
 183 Docker container, the user uid/gid inside Docker has already been changed.
 184 <!-- end-section-note -->
 185
 186 Use following commands to replace ID `1664` with your user and group ID:
 187
 188 ```bash
 189 # Set the Docker container name (e.g. agl-xds-xxx where xxx is USERNAME@MACHINENAME-IDX-NAME).
 190 export CONTAINER_NAME=agl-xds-seb@laptop-0-seb
 191 docker ps | grep -q ${CONTAINER_NAME} || echo "ERROR: No container name \"${CONTAINER_NAME}\" please set a valid CONTAINER_NAME before you continue"
 192
 193 # Kill all processes of with the user ID `devel`. This includes the running xds-server.
 194 docker exec ${CONTAINER_NAME} bash -c "/bin/loginctl kill-user devel"
 195
 196 # Change user and group IDs inside Docker to match your user and group IDs.
 197 docker exec ${CONTAINER_NAME} bash -c "usermod -u $(id -u) devel"
 198 docker exec ${CONTAINER_NAME} bash -c "groupmod -g $(id -g) devel"
 199
 200 # Update file ownerships.
 201 docker exec ${CONTAINER_NAME} bash -c "chown -R devel:devel /home/devel /tmp/xds*"
 202
 203 # Restart the devel autologin service.
 204 docker exec ${CONTAINER_NAME} bash -c "systemctl restart autologin"
 205
 206 # Restart xds-server as a service. The ssh port 2222 might depend on your container ID.
 207 ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server"
 208 ```
 209 ### Manually setup the Docker Password
 210
 211 If you forget the password set for the container , you wont be able to ssh into the container and check on the files created.
 212 For such a time , you need to set up a new password for the container. Use the following commands to do just that:
 213
 214 ```bash
 215 # This will let you access the bash shell inside the container as root
 216 docker exec -it ${CONTAINER_NAME} /bin/bash
 217
 218 # Change the password of the user (root or devel)
 219 passwd ${USER}
 220 ```
 221 ### Check if xds-server is Running (open XDS webapp)
 222
 223 When the container starts up, `xds-server` automatically starts as a
 224 user service.
 225
 226 If the container is running on your localhost, you can access a basic web
 227 application to check on `xds-server`:
 228
 229 ```bash
 230 xdg-open http://localhost:8000
 231 ```
 232
 233 From a shell prompt, you can check status, stop, and start `xds-server`
 234 using the following commands:
 235
 236 ```bash
 237 # Status XDS server
 238 ssh -p 2222 devel@localhost systemctl --user status xds-server.service
 239
 240 # Stop XDS server
 241 ssh -p 2222 devel@localhost systemctl --user stop xds-server.service
 242
 243 # Start XDS server
 244 ssh -p 2222 devel@localhost systemctl --user start xds-server.service
 245
 246 # Get XDS server logs
 247 ssh -p 2222 devel@localhost journalctl --user --unit=xds-server.service --output=cat
 248 ```
 249
 250 `xds-server` should be up and running.
 251 You can now install AGL SDKs.
 252 See the
 253 "[AGL SDKs](install-sdk.html)" section for more information.
 254
 255 ## VirtualBox Appliance
 256
 257 This section describes how to install the server part (`xds-server`)
 258 into a guest Virtual Machine (VM) supported by
 259 [VirtualBox](https://en.wikipedia.org/wiki/VirtualBox).
 260 VirtualBox allows the creation and management of guest virtual
 261 machines that run versions and derivations on many types of systems
 262 (e.g. Linux, Window, MacOS, and so forth).
 263
 264 ### Prerequisites
 265
 266 The system on which you are installing the server part must have
 267 VirtualBox installed.
 268 For information on how to install VirtualBox, see the
 269 [VirtualBox documentation](https://www.virtualbox.org/wiki/Downloads).
 270
 271 ### Get the Appliance
 272
 273 Use the following command to load the pre-built AGL SDK
 274 appliance image, which includes `xds-server`:
 275
 276 ```bash
 277 wget http://iot.bzh/download/public/XDS/appliance/xds-vm-debian9_latest.ova
 278 ```
 279
 280 ### Clean the Old Appliance
 281
 282 Only one appliance can exist on the machine.
 283 Consequently, you must remove any existing XDS appliance.
 284 Use the following commands:
 285
 286 ```bash
 287 # Get the virtual machine name
 288 VDS_VMNAME=$(VBoxManage list vms | grep xds-vm-debian | cut -d "\"" -f2)
 289 echo ${VDS_VMNAME}
 290
 291 # Remove the old XDS appliance
 292 [ -n ${VDS_VMNAME} ] && VBoxManage controlvm ${VDS_VMNAME} poweroff
 293 [ -n ${VDS_VMNAME} ] && VBoxManage unregistervm ${VDS_VMNAME} --delete
 294 ```
 295
 296 ### Create and Start a New Appliance
 297
 298 You can create a new appliance by using a provided script or by
 299 using the VirtualBox GUI:
 300
 301 ```bash
 302 # Import image into VirtualBox
 303 VBoxManage import ./xds-vm-debian9_latest.ova
 304
 305 # Check import result
 306 VDS_VMNAME=$(VBoxManage list vms | grep xds-vm-debian | cut -d "\"" -f2)
 307 echo ${VDS_VMNAME}
 308 ```
 309
 310 Add a share folder to the appliance.
 311 You must use "path-mapping sharing type for projects":
 312
 313 ```bash
 314 # Create local share folder
 315 mkdir -p $HOME/xds-workspace
 316
 317 #Add share folder to appliance
 318 VBoxManage sharedfolder add ${VDS_VMNAME} --name XDS-workspace --hostpath $HOME/xds-workspace
 319 ```
 320
 321 Use the following command to start the appliance:
 322
 323 ```bash
 324 # Start XDS appliance
 325 [ -n ${VDS_VMNAME} ] && VBoxManage startvm ${VDS_VMNAME}
 326 ```
 327
 328 ### Appliance Settings
 329
 330 The image exposes the following network ports, which are NAT mode:
 331
 332 - 8000 : `xds-server` to serve XDS basic web page
 333 - 2222 : ssh
 334
 335 ### Check if xds-server is Running
 336
 337 When the container in the virtual machine starts up, the `xds-server` automatically starts.
 338
 339 To check if `xds-server` is correctly installed and running, you can access the
 340 XDS basic web page and refer to the instructions:
 341
 342 ```bash
 343 # If the container/appliance is running on your local host
 344 # (else replace localhost with the name or the ip of the machine running the container)
 345 xdg-open http://localhost:8000
 346 ```
 347
 348 `xds-server` should be up and running.
 349 You can now install AGL SDKs.
 350 See the
 351 "[AGL SDKs](install-sdk.html)" section for more information.
 352
 353
 354 ## Native
 355
 356 This section describes how to install the server part (`xds-server`) 'natively'
 357 on a Linux-based system.
 358
 359 <!-- section-note -->
 360 **NOTE:**
 361 Hosts running a Linux distribution are the only hosts that support native
 362 installation of the server part.
 363 <!-- end-section-note -->
 364
 365 ### Prerequisites
 366
 367 The system on which you are installing the server part must have
 368 `python3` installed, which allows `xds-server` to manage AGL SDKs.
 369
 370 #### Installing Packages for Debian
 371
 372 Use the following commands to install packages for
 373 `xds-server` on Debian-based systems:
 374
 375 ```bash
 376 # Set 'DISTRO' (e.g. xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, Debian_8.0, Debian_9.0)
 377 export DISTRO="xUbuntu_16.04"
 378
 379 # Set AGL_RELEASE (e.g. AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master)
 380 export AGL_RELEASE="AGL_Master"
 381
 382 wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/Release.key | sudo apt-key add -
 383 sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <<EOF
 384 deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/ ./
 385 EOF"
 386
 387 sudo apt-get update
 388 sudo apt-get install agl-xds-server
 389
 390 # Install python3
 391 sudo apt-get install python3
 392 ```
 393
 394 #### Install Packages for OpenSUSE
 395
 396 Use the following commands to install packages for
 397 `xds-server` on OpenSUSE-based systems:
 398
 399 ```bash
 400 # Set DISTRO (openSUSE_Leap_42.3, openSUSE_Leap_15.0, openSUSE_Tumbleweed)
 401 export DISTRO="openSUSE_Leap_15.0"
 402
 403 # Set AGL_RELEASE (AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master)
 404 export AGL_RELEASE="AGL_Master"
 405
 406 sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/isv:LinuxAutomotive:${AGL_RELEASE}.repo
 407
 408 sudo zypper ref
 409 sudo zypper install agl-xds-server
 410
 411 # Install python3
 412 sudo zypper install python3
 413 ```
 414
 415 #### Configure the xds-server
 416
 417 Configuring the `xds-server` occurs through a JSON configuration file
 418 named `server-config.json`.
 419 All fields in the JSON configuration file are optional.
 420 Consequently, you can skip this configuration step if you want to use
 421 the default settings in the JSON file.
 422
 423 If you want to customize or alter the default configuration, see the
 424 "[Configuration chapter of xds-server](../part-2/1_xds-server/2_config.html)"
 425 section for details on the JSON configuration file.
 426
 427 #### Start and Stop xds-server
 428
 429 You can manage `xds-server` as a
 430 [systemd](https://en.wikipedia.org/wiki/Systemd) service by using
 431 the following commands:
 432
 433 ```bash
 434 # Status XDS server:
 435 systemctl --user status xds-server.service
 436
 437 # Stop XDS server
 438 systemctl --user stop xds-server.service
 439
 440 # Start XDS server
 441 systemctl --user start xds-server.service
 442
 443 # Get XDS server logs
 444 systemctl --user --unit=xds-server.service --output=cat
 445 ```
 446
 447 To check if `xds-server` is correctly installed and running, you can access
 448 the XDS web interface through your browser:
 449
 450 ```bash
 451 xdg-open http://localhost:8000
 452 ```
 453
 454 Alternatively, you can use the following `curl` command:
 455
 456 ```bash
 457 curl http://localhost:8000/api/v1/version
 458 ```
 459