summaryrefslogtreecommitdiffstats
path: root/docs/part-1/2_install-xds-server.md
blob: c992f35a4ba8ce9f5828a003b13ff37cb77371e2 (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
# Installing XDS server

Depending of your configuration, this step is necessary or not.

In other words **you are a developer and plan to use/connect to an existing `xds-server`**
running on your local network (On-Premise config) or in the Cloud (SaaS config),
**you don't need to install the server part and you can skip this step**.

For others (standalone config or administrators that want to install an
On-Premise solution) xds-server must be installed.

Several installation types are supported :

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

## Installation based on Docker container

### Prerequisites

Docker is installed on the host machine, please refer to [Docker documentation](https://docs.docker.com/engine/installation/) for more details.

### Get the container

Load the pre-build AGL SDK docker image including `xds-server`:

```bash
seb@laptop ~$ wget -O - http://iot.bzh/download/public/2017/XDS/docker/docker_agl_worker-xds-latest.tar.xz | docker load
```

You should get `docker.automotivelinux.org/agl/worker-xds:X.Y` image

```bash
# List image that we just load
seb@laptop ~$ docker images "docker.automotivelinux.org/agl/worker-xds*"

docker.automotivelinux.org/agl/worker-xds       4.0              786d65b2792c        6 days ago          654MB
```

### Create and start a new container

Use provided script to create a new docker container and start it:

```bash
# Get script
seb@laptop ~$ wget https://raw.githubusercontent.com/iotbzh/xds-server/master/scripts/xds-docker-create-container.sh

# Create new XDS worker container
seb@laptop ~$ bash ./xds-docker-create-container.sh

# Check that new container is running
seb@laptop ~$ docker ps | grep worker-xds

b985d81af40c        docker.automotivelinux.org/agl/worker-xds:3.99.1       "/usr/bin/wait_for..."   6 days ago           Up 4 hours          0.0.0.0:8000->8000/tcp, 0.0.0.0:69->69/udp, 0.0.0.0:10809->10809/tcp, 0.0.0.0:2222->22/tcp    agl-xds-seb@laptop-0-seb
```

Note that you can also add a new shared directory using `--volume` option in order
to use for example with Path-Mapping folder type.

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

### Check if xds-server is running

`xds-server` is automatically started as a service on container startup.

To check if xds-server is correctly install and running, you can access the basic
web page that gives you some instructions:

```bash
# if container is running on your local host
# (else replace localhost by the name or the ip of the machine running the container)
seb@laptop ~$ xdg-open http://localhost:8000
```

`xds-server` is now up and running, you can now install AGL SDKs, please refer
to next chapter named [Installing AGL SDKs](3_install-sdks.md#installing-agl-sdks)

### Container settings

This container (ID=0) exposes following ports:

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

This container also creates the following volumes (sharing directories 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 |

<!-- note -->
Please refer to [part 2 - xds-server](../part-2/1_xds-server.md) documentation
for additional info.
<!-- endnote -->

## Installation based on Virtual Machine appliance

### Prerequisites

> VirtualBox is installed on the host machine

please refer to [VirtualBox documentation](https://www.virtualbox.org/wiki/Downloads) for more details.

### Get the appliance

Load the pre-build AGL SDK appliance image including `xds-server`:

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

### Clean old appliance

You must have one and one xds appliance only.

So, at first remove the oldest xds appliance.

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

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

### Create and start a new appliance

Use provided script to create a new appliance or you can use the UI of VirtualBox:

```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}

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

### Appliance settings

This container (ID=0) exposes following ports:

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

## Check if xds-server is running

`xds-server` is automatically started as a service on container startup.

To check if xds-server is correctly install and running, you can access the basic web page that gives you some instructions:

```bash
# if container/appliance is running on your local host
# (else replace localhost by the name or the ip of the machine running the container)
seb@laptop ~$ xdg-open http://localhost:8000
```

`xds-server` is now up and running, you can now install AGL SDKs, please refer
to next chapter named [Installing AGL SDKs](3_install-sdks.md#installing-agl-sdks)

## Native installation

You can chose to install xds-server 'natively' instead of within a docker
container but note that only Linux host OSes are supported and tested for native
installation !

### Install packages for debian distro type

```bash
# 'DISTRO' can be set to { xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, Debian_8.0, Debian_9.0}
seb@laptop ~$  export DISTRO="xUbuntu_16.04"

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

seb@laptop ~$  sudo apt-get update
seb@laptop ~$  sudo apt-get install agl-xds-server
```

### Install packages for openSUSE distro type

```bash
# DISTRO can be set to {openSUSE_Leap_42.2, openSUSE_Leap_42.3, openSUSE_Tumbleweed}
seb@laptop ~$  export DISTRO="openSUSE_Leap_42.2"

seb@laptop ~$  sudo zypper ar http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/app-Development/${DISTRO}/isv:LinuxAutomotive:app-Development.repo

seb@laptop ~$  sudo zypper ref
seb@laptop ~$  sudo zypper install agl-xds-server
```

### Configure xds-server

<!-- note -->
**Optional step**: skip this chapter if you plan to use default settings
<!-- endnote -->

When `xds-server` is started as a systemd service, default environment variables
are set into `/etc/default/xds-server` file.

`xds-server` configuration is also driven by a JSON config file (`server-config.json`),
and default JSON config is `/etc/xds/server/server-config.json`.

<!-- note -->
**Note:** you can use your own JSON config by settings `APP_CONFIG` variable of
`/etc/default/xds-server` file to your file, for example `/home/MYUSER/.xds/server/server-config.json`
<!-- endnote -->

Supported fields in JSON configuration file are :

- **httpPort** : HTTP port of client webapp/REST API
- **webAppDir** : location of client web application (default: webapp/dist)
- **shareRootDir** : root directory where projects will be copied
- **logsDir**  : directory to store logs (eg. syncthing output)
- **sdkScriptsDir** : directory where scripts, used to managed SDKs, are installed
- **syncthing.binDir** : syncthing binaries directory (default: executable directory)
- **syncthing.home"** : syncthing home directory (usually .../syncthing-config)
- **syncthing.gui-address** : syncthing gui url (default <http://localhost:8385>)
- **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated)

All fields are optional and example below corresponds to the default values:

```json
{
    "httpPort": 8000,
    "webAppDir": "webapp/dist",
    "shareRootDir": "${HOME}/.xds/server/projects",
    "logsDir": "/tmp/logs",
    "sdkScriptsDir": "${EXEPATH}/scripts/sdks",
    "syncthing": {
        "binDir": "./bin",
        "home": "${HOME}/.xds/server/syncthing-config",
        "gui-address": "http://localhost:8385",
        "gui-apikey": "123456789",
    }
}
```

>**Note:** environment variables are supported by using `${MY_VAR}` syntax.

### Start/Stop xds-server

`xds-server` can be managed as a systemd service with the following commands:

```bash
# Status XDS server:
seb@laptop ~$ systemctl --user status xds-server.service

# Stop XDS server
seb@laptop ~$ systemctl --user stop xds-server.service

# Start XDS server
seb@laptop ~$ systemctl --user start xds-server.service

# Get XDS server logs
seb@laptop ~$ systemctl --user --unit=xds-server.service --output=cat
```

To check if xds-server is correctly install and running, you can access the web
interface, using a web browser :

```bash
seb@laptop ~$ xdg-open http://localhost:8000
```

or get the current version using the following curl command:

```bash
seb@laptop ~$ curl http://localhost:8000/api/v1/version
```