Various review edits for XDS

Took care of review comments from Sebastien
to clear up some terminlogy, update the
create-app-workflow.png image to include
declaring a project. Fixed a link to the
XDS user guide to be guppy-specific.

Included more explanation regarding
aborting an ongoing installation.

v2: squased version due to files being (re-)moved

Change-Id: I48c20d8e0b105f1e26b68b574b2c5d2b56eecb61
Signed-off-by: Scott RifenbarK <srifenbark@gmail.com>
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>

1 files changed, 449 insertions, 0 deletions

diff --git a/docs/part-1/server-part.md b/docs/part-1/server-part.md
new file mode 100644
index 0000000..afa27c7
--- /dev/null
+++ b/docs/part-1/server-part.md
@@ -0,0 +1,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
+```
+