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
Virtual Machine Linux, MacOS or Windows VirtualBox Appliance
Native Linux Native

Docker Container

This section describes how to install the server part (xds-server) into a Docker 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.

  • Aside from having Docker installed, users must be part of a docker group. 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 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:

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:

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:

# 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" 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 ```

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 section.

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.

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.

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

# 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:

xdg-open http://localhost:8000

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

# 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" 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. 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.

Get the Appliance

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

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:

# 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:

# 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":

# 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:

# 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:

# 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" section for more information.

Native

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

NOTE: Hosts running a Linux distribution are the only hosts that support native installation of the server part.

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:

# 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:

# 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" section for details on the JSON configuration file.

Start and Stop xds-server

You can manage xds-server as a systemd service by using the following commands:

# 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:

xdg-open http://localhost:8000

Alternatively, you can use the following curl command:

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