Update XDS documentation

 - remove documentation duplication for xds-server.

Change-Id: Icd76d3a65a3a2ad39438524b0d43d33c0a61d077
Signed-off-by: Ronan Le Martret <ronan.lemartret@iot.bzh>
Signed-off-by: Sebastien Douheret <sebastien.douheret@iot.bzh>

6 files changed, 192 insertions, 88 deletions

diff --git a/docs/part-1/0_Abstract.md b/docs/part-1/0_Abstract.md
index 8def883..e2620e6 100644
--- a/docs/part-1/0_Abstract.md
+++ b/docs/part-1/0_Abstract.md
@@ -10,22 +10,29 @@ This documentation is available :
 - online: [http://docs.automotivelinux.org/docs/devguides/en/dev/#xcross-development-system-user's-guide](http://docs.automotivelinux.org/docs/devguides/en/dev/#xcross-development-system-user's-guide)
 - PDF file: [http://iot.bzh/download/public/XDS/docs/XDS_UsersGuide.pdf](http://iot.bzh/download/public/XDS/docs/XDS_UsersGuide.pdf)
 
-The first goal of XDS is to provide a multi-platform cross development tool with
-near-zero installation.
+The first goal of XDS is to provide a multi-platform cross development tool with near-zero installation.
+
 The second goal is to keep application sources locally (on user's machine) to
 make it compatible with existing IT policies (e.g. corporate backup or SCM),
 and let user to continue to work as usual (use his favorite editor,
 keep performance while editing/browsing sources).
 
-The two main blocks that compose XDS are the client part (`xds-agent`) running
-on the user's machine and the server part (`xds-server`) running somewhere in a container or on a server machine (on local network or cloud).
+The two main blocks that compose XDS:
+
+- The client part (`xds-agent`) running on the user's machine and
+- The server part (`xds-server`) running somewhere in a container or on a server machine (on local network or cloud).
 
 ![](./pictures/xds-block-diagram.png){:: style="width:98%;"}
 
 <!-- pagebreak -->
 
-The client part (`xds-agent`) is portable and is running on Linux, Windows or
-MacOS machine and the following 3 main configurations are supported:
+The client part (`xds-agent`) is portable and is running on:
+
+- Linux
+- Windows
+- MacOS
+
+The following 3 main configurations are supported:
 
 - standalone (or local) config
 - On-Premise (local network)
diff --git a/docs/part-1/1_install-client.md b/docs/part-1/1_install-client.md
index b482dc9..255401d 100644
--- a/docs/part-1/1_install-client.md
+++ b/docs/part-1/1_install-client.md
@@ -2,17 +2,21 @@
 
 [xds-agent](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-agent.git) is a client tool that must run
 on your machine (user / developer host) to be able to use XDS.
+
 You should establish the following chain:
 
-Client (eg. `xds-cli` or XDS Dashboard) and `xds-agent` is running on your machine
-and `xds-server` is running on a remote server and/or in a container.
-Exchanges between these 3 tools are done though HTTP and Websocket protocols
-and default url/port mentioned in schema below can be change using config files.
+- XDS Client: (`xds-cli` or XDS Dashboard).
+- XDS Agent: (`xds-agent`) running on your machine.
+- XDS Server  (`xds-server`) running on a remote server and/or in a container.
+
+Exchanges between these 3 tools are done though HTTP and Websocket protocols.
+
+Default url/port mentioned in schema below can be change using config files.
 
 ![XDS blocks chain](./pictures/xds-block-chain.png)
 
 Installation of other XDS client tools, such as `xds-cli` or `xds-gdb` is
-optional and depends of what you want to do :
+optional and depends of what you want to do:
 
 - [xds-cli](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-cli.git) : command line tool to used to interact with XDS (also used by IDE integration).
 - [xds-gdb](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-gdb.git) : requested for debugging application.
@@ -71,14 +75,18 @@ sudo zypper install agl-xds-gdb
 XDS-agent is a client tool that must run on your local / user development
 machine when you use XDS.
 
-For Linux distro, a user systemd service is provided, so you just need to enable
-if you want to start it automatically at boot and you can also start it
-immediately using following commands:
+For Linux distro, a user systemd service is provided, `xds-agent.service`.
+
+To start it automatically at boot and you can enable it using following commands:
 
 ```bash
 # Enable xds-agent service at boot
 systemctl --user enable xds-agent.service
+```
+
+To start the XDS-agent service:
 
+```bash
 # Manually start xds-agent service
 systemctl --user start xds-agent.service
 
diff --git a/docs/part-1/2_install-xds-server.md b/docs/part-1/2_install-xds-server.md
index 3609bd7..cbbca44 100644
--- a/docs/part-1/2_install-xds-server.md
+++ b/docs/part-1/2_install-xds-server.md
@@ -9,7 +9,7 @@ running on your local network (On-Premise config) or in the Cloud (SaaS config),
 For others (standalone config or administrators that want to install an
 On-Premise solution) xds-server must be installed.
 
-Several installation types are supported :
+Several installation types are supported:
 
 | Install type | Supported OS | Section to refer |
 |--------------|--------------|------------------|
@@ -19,7 +19,7 @@ Several installation types are supported :
 
 ## Installation based on Docker container
 
-### Prerequisites
+### Docker container prerequisites
 
 Docker is installed on the host machine, please refer to [Docker documentation](https://docs.docker.com/engine/installation/) for more details.
 
@@ -37,27 +37,47 @@ You should get `docker.automotivelinux.org/agl/worker-xds:X.Y` image
 # List image that we just load
 docker images "docker.automotivelinux.org/agl/worker-xds*"
 
-docker.automotivelinux.org/agl/worker-xds       4.0              786d65b2792c        6 days ago          654MB
+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
 
-Use provided script to create a new docker container and start it:
+Use provided script to create a new docker image and start a new container:
 
 ```bash
 # Get script
-wget https://raw.githubusercontent.com/iotbzh/xds-server/master/scripts/xds-docker-create-container.sh
+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
 bash ./xds-docker-create-container.sh
 
 # Check that new container is running
 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
+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:69->69/udp, 0.0.0.0:10809->10809/tcp, 0.0.0.0:2222->22/tcp   agl-xds-HOSTNAME-0-USERNAME
 ```
 
-Note that you can also add a new shared directory using `--volume` option in order
+This container exposes following ports:
+
+| Port number | Description                                 |
+|-------------|---------------------------------------------|
+|     8000    | `xds-server`: serve XDS webapp and REST API |
+|      69     | TFTP                                        |
+|     2222    | ssh                                         |
+
+This container also creates the following volumes (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 |
+
+<!-- note -->
+**Note:**
+
+You can add a new shared directory using `--volume` option in order
 to use for example with Path-Mapping folder type.
 
 ```bash
@@ -65,47 +85,95 @@ to use for example with Path-Mapping folder type.
 bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME/my-workspace
 ```
 
-### Check if xds-server is running
+You can change docker used port with `-id` option
 
-`xds-server` is automatically started as a service on container startup.
+```bash
+# Create new XDS worker container with a different port number
+bash ./xds-docker-create-container.sh -id ${ID}
 
-To check if xds-server is correctly install and running, you can access the basic
-web page that gives you some instructions:
+# Check that 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:(2222+ID)->22/tcp, 0.0.0.0:(69+ID)->69/udp, 0.0.0.0:(8000+ID)->8000/tcp, 0.0.0.0:(10809+ID)->10809/tcp   agl-xds-HOSTNAME-ID-USERNAME
+```
+
+<!-- endnote -->
+
+#### Manually setup docker user id
+
+<!-- note -->
+**Note:**
+
+If you used `xds-docker-create-container.sh` script to create XDS
+docker container, user uid/gid inside docker has already been changed by this script.
+<!-- endnote -->
+
+If you plan to use **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 name inside docker is set `devel` (id `1664`).
+
+Use following commands to replace id `1664` with your user/group id:
+
+```bash
+# Set docker container name to use (usually 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"
+
+# First kill all processes of devel user (including running xds-server)
+docker exec ${CONTAINER_NAME} bash -c "/bin/loginctl kill-user devel"
+
+# Change user and group id inside docker to match your ids
+docker exec ${CONTAINER_NAME} bash -c "usermod -u $(id -u) devel"
+docker exec ${CONTAINER_NAME} bash -c "groupmod -g $(id -g) devel"
+
+# Update some files ownership
+docker exec ${CONTAINER_NAME} bash -c "chown -R devel:devel /home/devel /tmp/xds*"
+
+# Restart devel autologin service
+docker exec ${CONTAINER_NAME} bash -c "systemctl restart autologin"
+
+# Restart xds-server as a service (ssh port 2222 may depend on your container ID)
+ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server"
+```
+
+### Check if xds-server is running (open XDS webapp)
+
+**`xds-server` is automatically started** as a service on container startup.
+
+If the container is running on your localhost, you can access to a basic web
+application:
 
 ```bash
-# if container is running on your local host
-# (else replace localhost by the name or the ip of the machine running the container)
 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)
+If needed you can status / stop / start  it manually using following commands:
 
-### Container settings
+```bash
+# Status XDS server:
+ssh -p 2222 devel@localhost systemctl --user status xds-server.service
 
-This container (ID=0) exposes following ports:
+# Stop XDS server
+ssh -p 2222 devel@localhost systemctl --user stop xds-server.service
 
-- 8000 : `xds-server` to serve XDS basic web page
-- 69   : TFTP
-- 2222 : ssh
+# Start XDS server
+ssh -p 2222 devel@localhost systemctl --user start xds-server.service
 
-This container also creates the following volumes (sharing directories between
-inside and outside docker):
+# Get XDS server logs
+ssh -p 2222 devel@localhost journalctl --user --unit=xds-server.service --output=cat
+```
 
-| 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 |
+`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.html#installing-agl-sdks)
 
 <!-- note -->
-Please refer to [part 2 - xds-server](../part-2/1_xds-server.md#sdk-cross-toolchain-management) documentation
+Please refer to [part 2 - xds-server](../part-2/1_xds-server.html#sdk-cross-toolchain-management) documentation
 for additional info.
 <!-- endnote -->
 
 ## Installation based on Virtual Machine appliance
 
-### Prerequisites
+### Virtual Machine appliance prerequisites
 
 > VirtualBox is installed on the host machine
 
@@ -131,6 +199,7 @@ VDS_VMNAME=$(VBoxManage list vms | grep xds-vm-debian | cut -d "\"" -f2)
 echo ${VDS_VMNAME}
 
 # Remove old XDS appliance
+[ -n ${VDS_VMNAME} ] && VBoxManage controlvm ${VDS_VMNAME} poweroff
 [ -n ${VDS_VMNAME} ] && VBoxManage unregistervm ${VDS_VMNAME} --delete
 ```
 
@@ -150,6 +219,18 @@ echo ${VDS_VMNAME}
 [ -n ${VDS_VMNAME} ] && VBoxManage startvm ${VDS_VMNAME}
 ```
 
+**Mandatory**:
+
+Add share folder to appliance, to allow files sharing using pathmap method:
+
+```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
+```
+
 ### Appliance settings
 
 This image exposes following network ports (NAT mode):
@@ -171,7 +252,7 @@ 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)
+to next chapter named [Installing AGL SDKs](3_install-sdks.html#installing-agl-sdks)
 
 ## Native installation
 
@@ -212,23 +293,6 @@ sudo zypper install agl-xds-server
 **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`
-
-- `CloudSync` (AKA syncthing) synchronzation type can also be disabled when
-`"syncthing"` key is not defined in JSON configuration file.
-
-<!-- endnote -->
-
 Please refer to [Configuration chapter of xds-server](../part-2/1_xds-server.html#configuration)
 documentation for more details about JSON configuration file.
 
diff --git a/docs/part-1/3_install-sdks.md b/docs/part-1/3_install-sdks.md
index 4755b95..67a6002 100644
--- a/docs/part-1/3_install-sdks.md
+++ b/docs/part-1/3_install-sdks.md
@@ -1,8 +1,9 @@
 # Installing AGL SDKs
 
 To build your AGL services or AGL applications using XDS you must install a SDK
-matching the target/board you want to use. A SDK is a package that includes all
-tools you need to cross-build and cross-debug your service/application.
+matching the target/board you want to use.
+
+A SDK is a package that includes all tools you need to cross-build and cross-debug your service/application.
 
 You can generate AGL SDK for the board you want to use or you can download
 a pre-packaged AGL SDK.
@@ -75,13 +76,15 @@ is located in `$HOME/xds-workspace/sdks` directory
 ## Install a new SDK from XDS Dashboard
 
 Open XDS-Dashboard in web-browser and select `SDKs` entry in left side menu.
+
 Then switch to `SDKs MANAGEMENT` view :
 
 ![](../part-1/pictures/xds-dashboard-sdks-mgt.png){:: style="margin:auto; display:flex"}
 
 Use filter boxes to find the SDK you want to install and then click on plus
-icon (Actions column) to start installation. SDK download and installation
-process may take several minutes and output of installation script (output of
+icon (Actions column) to start installation.
+
+SDK download and installation process may take several minutes and output of installation script (output of
 `add` script mentioned in above chapter).
 
 ![](../part-1/pictures/xds-dashboard-sdks-install.png){:: style="margin:auto; display:flex"}
diff --git a/docs/part-1/4_build-first-app.md b/docs/part-1/4_build-first-app.md
index 997a4b9..f6810d1 100644
--- a/docs/part-1/4_build-first-app.md
+++ b/docs/part-1/4_build-first-app.md
@@ -15,6 +15,7 @@
 
 Let's use _helloworld-native-application_ project as example, so you need first to clone
 this project into a directory that will be accessible by `xds-server`.
+
 Depending of the project sharing method:
 
 - Cloud sync: you can clone project anywhere on your local disk,
@@ -40,7 +41,9 @@ git clone --recursive https://github.com/iotbzh/helloworld-native-application.gi
 ### Declare project using XDS Dashboard
 
 Use XDS Dashboard to declare your project. Open a browser and connect to XDS
-Dashboard. URL depends of your config, for example `http://localhost:8800`
+Dashboard.
+
+URL depends of your config, for example `http://localhost:8800`
 
 Open the right sidebar and select `Projects` entry to open project page and then
 create/declare a new project by with the plus icon:
@@ -54,14 +57,17 @@ Set `Sharing Type` and paths according to your needs.
 ![](./pictures/xds-dashboard-prj-1.png){:: style="width:90%; max-width:560px; margin:auto; display:flex"}
 
 Note that XDS creates (if not already exists) a file named `xds-project.conf`
-when you declare a new project. This file may be very useful when you plan to
-use XDS client tools such as `xds-cli` or `xds-gdb`.
+when you declare a new project.
+
+This file may be very useful when you plan to use XDS client tools such as `xds-cli` or `xds-gdb`.
 
 <!-- note -->
-**Note:** when `Path mapping` type is selected, you must clone your project into
+**Note:**
+
+When `Path mapping` type is selected, you must clone your project into
 `$HOME/xds-workspace` directory (named **Local Path** in modal window).
 
-If XDS server is running in the XDS docker container (see [Installation based on Docker container](./2_install-xds-server.md#installation-based-on-docker-container) ),
+If XDS server is running in the XDS docker container (see [Installation based on Docker container](./2_install-xds-server.html#installation-based-on-docker-container) ),
 the **Server Path** must be set to `/home/devel/xds-workspace/xxx` where xxx is your
 project directory name.
 
@@ -108,20 +114,26 @@ f9904f70-d441-11e7-8c59-3c970e49ad9b     Project_helloworld-service
 ```
 
 XDS tools, including `xds-cli` are installed by default in `/opt/AGL/bin`
-directory and this path has been added into your PATH variable. If it is not the
-case, just add it manually using `export PATH=${PATH}:/opt/AGL/bin` command line.
+directory and this path has been added into your PATH variable.
+
+If it is not the case, just add it manually using `export PATH=${PATH}:/opt/AGL/bin` command line.
 
 Now to refer your project, just use --id option or use `XDS_PROJECT_ID`
 environment variable.
 
 <!-- note -->
-**Note:** short id notation is also supported as soon as given id value is non ambiguous.
+**Note:**
+
+Short id notation is also supported as soon as given id value is non ambiguous.
+
 For example, to refer to Project_helloworld-native-application project listed
 in above command, you can simply use --id 40 instead of --id 4021617e-ced0-11e7-acd2-3c970e49ad9b
 <!-- endnote -->
 
 You also need to determine the ID of the cross SDK you want to use to cross build
-you application. To list installed SDK, use the following command:
+you application.
+
+To list installed SDK, use the following command:
 
 ```bash
 xds-cli sdks ls
@@ -133,6 +145,7 @@ List of installed SDKs:
 ```
 
 You are now ready to use XDS to for example cross build your project.
+
 Here is an example to build a project based on CMakefile:
 
 ```bash
@@ -209,7 +222,9 @@ EOF
 
 This chapter will show you how to create 2 configurations, one to compile your
 project natively (using native GNU gcc) and one to cross-compile your project
-using XDS. You can easily switch from one to other configuration using menu
+using XDS.
+
+You can easily switch from one to other configuration using menu
 **Run -> Set Project Configuration**.
 
 __Netbeans 8.x :__
@@ -334,7 +349,9 @@ AGL helloworld application based on cmake template.
 }
 ```
 
-> **Note:** You can also add your own keybindings to trig above tasks, for example:
+> **Note:**
+>
+> You can also add your own keybindings to trig above tasks, for example:
 >
 > ```json
 > // Build
diff --git a/docs/part-1/5_debug-first-app.md b/docs/part-1/5_debug-first-app.md
index 2a27177..01a183e 100644
--- a/docs/part-1/5_debug-first-app.md
+++ b/docs/part-1/5_debug-first-app.md
@@ -1,13 +1,13 @@
 # Debug your first AGL application
 
 Debug is based on gdb and you need to use `xds-gdb` as a wrapper on gdb to
-cross-debug your application. This tool allows you to debug an application built
-with XDS without the need to install gdb or any cross tools.
+cross-debug your application.
+
+This tool allows you to debug an application built with XDS without the need to install gdb or any cross tools.
 
 Two debugging models are supported:
 
 1. native debugging
-
 1. XDS remote debugging requiring an XDS agent/server setup and that allows you to cross debug your application.
 
 By default XDS debug model is used and you need to define `XDS_NATIVE_GDB`
@@ -30,11 +30,13 @@ variable to use native gdb debug mode instead.
 
 ### Configuration Variables
 
- `XDS_CONFIG`
- Config file defining `XDS_xxx` configuration variables. Variables of this file
- will overwrite inherited environment variables. Variables definition may be
- prefixed or not by "export" keyword.
- Here is an example of configuration file
+`XDS_CONFIG` Config file defining `XDS_xxx` configuration variables.
+
+Variables of this file will overwrite inherited environment variables.
+
+Variables definition may be  prefixed or not by "export" keyword.
+
+Here is an example of configuration file:
 
 ```bash
 # for example:
@@ -78,6 +80,7 @@ Local XDS agent url (default `http://localhost:8800`)
 
 Above `XDS_xxx` variables may also be defined within gdb init command file
 (see --command or -x option of genuine Gdb).
+
 You must respect the following syntax: commented line including `:XDS-ENV:` tag
 
 Example of gdb init file where we define project and sdk ID:
@@ -95,9 +98,10 @@ First the project you want to debug must be declared on an xds-server and this
 project may also has been built using using XDS (see [Create your first AGL application](./4_build-first-app.html) for more details).
 
 So to debug it you need to have the XDS agent - server chain in place and
-you also need the project and sdk unique id. You can find these IDs in project
-page of XDS dashboard or you can get them from command line using the `--list`
-option.
+you also need the project and sdk unique id.
+
+You can find these IDs in project page of XDS dashboard or you can get them from command line using the `--list` option.
+
 This option lists all existing projects ID:
 
 ```bash
@@ -107,6 +111,7 @@ xds-gdb --list
 Now to refer your project, just set `XDS_PROJECT_ID` and `XDS_SDK_ID` variables.
 
 You are now ready to use `xds-gdb` to for example cross debug your project.
+
 Here is an example to build and debug a project based on CMakefile and
 [AGL app-templates](https://git.automotivelinux.org/apps/app-templates/):