# 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 ``` **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. #### 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: ```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. **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: ```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 <