aboutsummaryrefslogtreecommitdiffstats
path: root/docs/part-1/server-part.md
blob: afa27c7117e662c0f949b4dea5c745e701a79fcd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
# Server Part

Depending on your situation, you must either install the
XDS server part or you can skip installation:

- If you are a developer and plan to connect to and use an existing `xds-server`
  that is running on your local network (On-Premise) or is available from
  the Cloud (SaaS), you do not need to install the server part.
- If you are configured for Standalone or you are an administrator
  that wants to install an On-Premise solution, you must install
  the server part.

This section describes three types of server part installations:

| Install type | Supported OS | Section to refer |
|--------------|--------------|------------------|
| Container | Linux or MacOS | [Docker Container](#docker-container) |
| Virtual Machine | Linux, MacOS or Windows | [VirtualBox Appliance](#virtualbox-appliance) |
| Native | Linux | [Native](#native) |

## Docker Container

This section describes how to install the server part (`xds-server`)
into a
[Docker Container](https://www.docker.com/resources/what-container)
on a Linux-based system or a MacOS system.

### Prerequisites

The system on which you are installing the server part
must meet both the following prerequisites:

- You must have Docker installed on the host machine.
  For information on installing Docker, see the
  [Docker documentation](https://docs.docker.com/engine/installation/).

- Aside from having Docker installed, users must be part of a
  docker
  [group](https://www.linux.com/learn/intro-to-linux/2017/12/how-manage-users-groups-linux).
  Enter the following command to display the system's groups and
  then search for and list the Docker groups:

  ```bash
  groups | grep docker
  ```

  If the users that plan on using the container are not part of the
  Docker group or the group does not exist, you must take steps.
  See the [docker post install instructions](https://docs.docker.com/install/linux/linux-postinstall/)
  for details on creating a Docker group and adding users.

  Following is a summary of the key commands:

  ```bash
  sudo groupadd docker
  sudo usermod -aG docker $USER
  # Log out and re-login so the system can re-evaluate the group membership
  # You might also need to start docker service manually

  sudo service docker start
  # or
  sudo systemctl start docker
  ```

### Get the Container

Use the following command to load the pre-built AGL
SDK Docker image, which includes `xds-server`:

```bash
wget -O - http://iot.bzh/download/public/XDS/docker/docker_agl_worker-xds-latest.tar.xz | docker load
```

The following command lists and displays information about the image:

```bash
docker images "docker.automotivelinux.org/agl/worker-xds*"

REPOSITORY                                  TAG                 IMAGE ID            CREATED             SIZE
docker.automotivelinux.org/agl/worker-xds   5.0                 877979e534ff        3 hours ago         106MB
```

### Create and Start a New Container

Running the following script creates a new Docker image and starts a new container:

```bash
# Get script
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'

# Create new XDS worker container (change the -id option value if you get a port conflict error)
bash ./xds-docker-create-container.sh -id 0

# Be sure the new container is running
docker ps | grep worker-xds
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
```

In the previous example, the container exposes following ports:

| Port number | Description                                 |
|-------------|---------------------------------------------|
|     8000    | `xds-server`: serve XDS webapp and REST API |
|     2222    | ssh                                         |

This container also creates the following volumes, which are shared folders between
inside and outside Docker:

| Directory on host | Directory inside docker | Comment |
|-------------------|-------------------------|---------|
| $HOME/xds-workspace | /home/devel/xds-workspace | XDS projects workspace location|
| $HOME/xds-workspace/.xdt_0 | /xdt | location to store SDKs |
| $USER_VOLUME | $USER_VOLUME | user path, see `--volume` option of `xds-docker-create-container.sh` script |

#### Optional Settings

When you create the container, you can use optional settings.
This section shows minimal settings to configure the container.
For more detailed `xds-server` configuration information including settings, see the
"[xds-server configuration](../part-2/1_xds-server/2_config.html)" section.

- **`--volume`**

  Adds a new shared directory using the `--volume` option (e.g.
  used with Path-Mapping folder types):

  ```bash
  # Create new XDS worker container and share extra '$HOME/my-workspace' directory
  bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME/my-workspace
  ```

- **`--id`**

  Changes the port used by Docker:

  ```bash
  # Create new XDS worker container with a different port number
  ID=3
  bash ./xds-docker-create-container.sh -id ${ID}

  # Check that new container is running (in example below id has been set to 3)
  docker ps | grep worker-xds
  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
  ```

  <!-- section-note -->
  **WARNING:**
  Changing the container id impacts the port number used to connect to `xds-server`.
  Consequently, you might need to adjust the `xds-agent` configuration in order
  to match the correct port number.

  In the previous example where the container id is set to "3", the export
  port number is `8003`.
  In this case, you must define "url" in the `xds-server` configuration as follows:

  ```json
  {
      ...
      "xdsServers": [
        {
          "url": "http://localhost:8003"
        }
      ],
      ...
  }
  ```

  For more information, see the
  [xds-agent configuration](../part-2/2_xds-agent/2_config.html) section.
  <!-- end-section-note -->

#### Manually Setup the Docker User ID

If you are using path-mapping sharing type for your projects, you need to
have the same user ID and group ID inside and outside Docker.

By default, user and group names inside Docker are `devel` and `1664`,
respectively.

<!-- section-note -->
**NOTE:**

If you used the `xds-docker-create-container.sh` script to create the XDS
Docker container, the user uid/gid inside Docker has already been changed.
<!-- end-section-note -->

Use following commands to replace ID `1664` with your user and group ID:

```bash
# Set the Docker container name (e.g. agl-xds-xxx where xxx is USERNAME@MACHINENAME-IDX-NAME).
export CONTAINER_NAME=agl-xds-seb@laptop-0-seb
docker ps | grep -q ${CONTAINER_NAME} || echo "ERROR: No container name \"${CONTAINER_NAME}\" please set a valid CONTAINER_NAME before you continue"

# Kill all processes of with the user ID `devel`. This includes the running xds-server.
docker exec ${CONTAINER_NAME} bash -c "/bin/loginctl kill-user devel"

# Change user and group IDs inside Docker to match your user and group IDs.
docker exec ${CONTAINER_NAME} bash -c "usermod -u $(id -u) devel"
docker exec ${CONTAINER_NAME} bash -c "groupmod -g $(id -g) devel"

# Update file ownerships.
docker exec ${CONTAINER_NAME} bash -c "chown -R devel:devel /home/devel /tmp/xds*"

# Restart the devel autologin service.
docker exec ${CONTAINER_NAME} bash -c "systemctl restart autologin"

# Restart xds-server as a service. The ssh port 2222 might depend on your container ID.
ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server"
```

### Check if xds-server is Running (open XDS webapp)

When the container starts up, `xds-server` automatically starts as a
user service.

If the container is running on your localhost, you can access a basic web
application to check on `xds-server`:

```bash
xdg-open http://localhost:8000
```

From a shell prompt, you can check status, stop, and start `xds-server`
using the following commands:

```bash
# Status XDS server
ssh -p 2222 devel@localhost systemctl --user status xds-server.service

# Stop XDS server
ssh -p 2222 devel@localhost systemctl --user stop xds-server.service

# Start XDS server
ssh -p 2222 devel@localhost systemctl --user start xds-server.service

# Get XDS server logs
ssh -p 2222 devel@localhost journalctl --user --unit=xds-server.service --output=cat
```

`xds-server` should be up and running.
You can now install AGL SDKs.
See the
"[AGL SDKs](install-sdks.html)" section for more information.

## VirtualBox Appliance

This section describes how to install the server part (`xds-server`)
into a guest Virtual Machine (VM) supported by
[VirtualBox](https://en.wikipedia.org/wiki/VirtualBox).
VirtualBox allows the creation and management of guest virtual
machines that run versions and derivations on many types of systems
(e.g. Linux, Window, MacOS, and so forth).

### Prerequisites

The system on which you are installing the server part must have
VirtualBox installed.
For information on how to install VirtualBox, see the
[VirtualBox documentation](https://www.virtualbox.org/wiki/Downloads).

### Get the Appliance

Use the following command to load the pre-built AGL SDK
appliance image, which includes `xds-server`:

```bash
wget http://iot.bzh/download/public/XDS/appliance/xds-vm-debian9_latest.ova
```

### Clean the Old Appliance

Only one appliance can exist on the machine.
Consequently, you must remove any existing XDS appliance.
Use the following commands:

```bash
# Get the virtual machine name
VDS_VMNAME=$(VBoxManage list vms | grep xds-vm-debian | cut -d "\"" -f2)
echo ${VDS_VMNAME}

# Remove the old XDS appliance
[ -n ${VDS_VMNAME} ] && VBoxManage controlvm ${VDS_VMNAME} poweroff
[ -n ${VDS_VMNAME} ] && VBoxManage unregistervm ${VDS_VMNAME} --delete
```

### Create and Start a New Appliance

You can create a new appliance by using a provided script or by
using the VirtualBox GUI:

```bash
# Import image into VirtualBox
VBoxManage import ./xds-vm-debian9_latest.ova

# Check import result
VDS_VMNAME=$(VBoxManage list vms | grep xds-vm-debian | cut -d "\"" -f2)
echo ${VDS_VMNAME}
```

Add a share folder to the appliance.
You must use "path-mapping sharing type for projects":

```bash
# Create local share folder
mkdir -p $HOME/xds-workspace

#Add share folder to appliance
VBoxManage sharedfolder add ${VDS_VMNAME} --name XDS-workspace --hostpath $HOME/xds-workspace
```

Use the following command to start the appliance:

```bash
# Start XDS appliance
[ -n ${VDS_VMNAME} ] && VBoxManage startvm ${VDS_VMNAME}
```

### Appliance Settings

The image exposes the following network ports, which are NAT mode:

- 8000 : `xds-server` to serve XDS basic web page
- 2222 : ssh

### Check if xds-server is Running

When the container in the virtual machine starts up, the `xds-server` automatically starts.

To check if `xds-server` is correctly installed and running, you can access the
XDS basic web page and refer to the instructions:

```bash
# If the container/appliance is running on your local host
# (else replace localhost with the name or the ip of the machine running the container)
xdg-open http://localhost:8000
```

`xds-server` should be up and running.
You can now install AGL SDKs.
See the
"[AGL SDKs](install-sdks.html)" section for more information.


## Native

This section describes how to install the server part (`xds-server`) 'natively'
on a Linux-based system.

<!-- section-note -->
**NOTE:**
Hosts running a Linux distribution are the only hosts that support native
installation of the server part.
<!-- end-section-note -->

### Prerequisites

The system on which you are installing the server part must have
`python3` installed, which allows `xds-server` to manage AGL SDKs.

#### Installing Packages for Debian

Use the following commands to install packages for
`xds-server` on Debian-based systems:

```bash
# Set 'DISTRO' (e.g. xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, Debian_8.0, Debian_9.0)
export DISTRO="xUbuntu_16.04"

# Set AGL_RELEASE (e.g. AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master)
export AGL_RELEASE="AGL_Master"

wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/Release.key | sudo apt-key add -
sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <<EOF
deb http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/ ./
EOF"

sudo apt-get update
sudo apt-get install agl-xds-server

# Install python3
sudo apt-get install python3
```

#### Install Packages for OpenSUSE

Use the following commands to install packages for
`xds-server` on OpenSUSE-based systems:

```bash
# Set DISTRO (openSUSE_Leap_42.3, openSUSE_Leap_15.0, openSUSE_Tumbleweed)
export DISTRO="openSUSE_Leap_15.0"

# Set AGL_RELEASE (AGL_ElectricEel, AGL_FunkyFlounder, AGL_Master)
export AGL_RELEASE="AGL_Master"

sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/${AGL_RELEASE}/${DISTRO}/isv:LinuxAutomotive:${AGL_RELEASE}.repo

sudo zypper ref
sudo zypper install agl-xds-server

# Install python3
sudo zypper install python3
```

#### Configure the xds-server

Configuring the `xds-server` occurs through a JSON configuration file
named `server-config.json`.
All fields in the JSON configuration file are optional.
Consequently, you can skip this configuration step if you want to use
the default settings in the JSON file.

If you want to customize or alter the default configuration, see the
"[Configuration chapter of xds-server](../part-2/1_xds-server/2_config.html)"
section for details on the JSON configuration file.

#### Start and Stop xds-server

You can manage `xds-server` as a
[systemd](https://en.wikipedia.org/wiki/Systemd) service by using
the following commands:

```bash
# Status XDS server:
systemctl --user status xds-server.service

# Stop XDS server
systemctl --user stop xds-server.service

# Start XDS server
systemctl --user start xds-server.service

# Get XDS server logs
systemctl --user --unit=xds-server.service --output=cat
```

To check if `xds-server` is correctly installed and running, you can access
the XDS web interface through your browser:

```bash
xdg-open http://localhost:8000
```

Alternatively, you can use the following `curl` command:

```bash
curl http://localhost:8000/api/v1/version
```