diff options
Diffstat (limited to 'docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/1_Installing_XDS /3.4.1.1_Server_Part.md')
| -rw-r--r-- | docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/1_Installing_XDS /3.4.1.1_Server_Part.md | 459 |
1 files changed, 0 insertions, 459 deletions
diff --git a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/1_Installing_XDS /3.4.1.1_Server_Part.md b/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/1_Installing_XDS /3.4.1.1_Server_Part.md deleted file mode 100644 index 6db9c98..0000000 --- a/docs/ATTIC/3_Developer_Guides/4_X(cross)_Development_System:_User's_Guide/1_Installing_XDS /3.4.1.1_Server_Part.md +++ /dev/null @@ -1,459 +0,0 @@ -# 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, password and group names inside Docker are `devel`, `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" -``` -### Manually setup the Docker Password - -If you forget the password set for the container , you wont be able to ssh into the container and check on the files created. -For such a time , you need to set up a new password for the container. Use the following commands to do just that: - -```bash -# This will let you access the bash shell inside the container as root -docker exec -it ${CONTAINER_NAME} /bin/bash - -# Change the password of the user (root or devel) -passwd ${USER} -``` -### 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-sdk.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-sdk.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 -``` - |