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>
author: Scott Rifenbark <srifenbark@gmail.com> 2019-04-11 15:31:33 +0200
committer: Scott Rifenbark <srifenbark@gmail.com> 2019-05-20 15:18:42 -0700
commit: 3635b88a18de43bbdd2373259ac65c02bc63c139 (patch)
tree: d3f83a07a32230b938b700cc59419c8c85f42282
parent: 8e5d6918c1a51ae3e948b95c30a357c700821e39 (diff)
24 files changed, 1413 insertions, 726 deletions
diff --git a/README.md b/README.md
index d6706ee..dc6b149 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,6 @@ This repository holds the XDS documentation.
 
 Resulting 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)
+- online: [http://docs.automotivelinux.org/docs/en/guppy/devguides/#xcross-development-system-user's-guide](http://docs.automotivelinux.org/docs/en/guppy/devguides/#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)
diff --git a/docs/README.md b/docs/README.md
index 89b908c..c349a3b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,7 +5,7 @@ cross build applications.
 
 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)
+- online: [http://docs.automotivelinux.org/docs/en/guppy/devguides/#xcross-development-system-user's-guide](http://docs.automotivelinux.org/docs/en/guppy/devguides/#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)
 
 <br>
diff --git a/docs/devguides-book.yml b/docs/devguides-book.yml
index fd5136a..dc8a033 100644
--- a/docs/devguides-book.yml
+++ b/docs/devguides-book.yml
@@ -6,36 +6,32 @@ books:
     description: XDS Docs documentation
     keywords:
     author: "IotBzh"
-    version: master
+    version: guppy
     chapters:
-    - url: part-1/0_Abstract.md
-      name: Getting Started
-    - name: Installing xds-server
-      children: 
-      - url: part-1/1_install-xds-server.md
-        name: Installation
-      - url: part-1/1-1_install-xds-server-docker.md
-        name: Based on Docker container
-      - url: part-1/1-2_install-xds-server-vm.md
-        name: Based on Virtual Machine appliance
-      - url: part-1/1-3_install-xds-server-native.md
-        name: Native installation
-    - url: part-1/2_install-client.md
-      name: Installing xds client tools
-    - url: part-1/3_install-sdks.md
-      name: Installing AGL SDKs
+    - url: part-1/xds-overview.md
+      name: Overview
+    - name: Installing XDS
+      children:
+      - url: part-1/server-part.md
+        name: Server Part
+      - url: part-1/client-part.md
+        name: Client Part
+      - url: part-1/install-sdk.md
+        name: AGL SDKs
     - name: Create your first AGL application
       children:
-      - url: part-1/4_build-first-app.md
-        name: Prerequisites
-      - url: part-1/4-1_build-first-app-setup.md
-        name: Setup
-      - url: part-1/4-2_build-first-app-cmd.md
-        name: Build using command line tool
-      - url: part-1/4-3_build-first-app-dashboard.md
-        name: Build using XDS Dashboard
-      - url: part-1/4-4_build-first-app-ide.md
-        name: Build using a source code editor / IDE
+      - url: part-1/create-app-overview.md
+        name: Overview
+      - url: part-1/create-app-requirements.md
+        name: Requirements
+      - url: part-1/create-app-get-source-files.md
+        name: Get the Source Files
+      - url: part-1/create-app-build-cmd-line.md
+        name: Build Using the Command Line
+      - url: part-1/create-app-build-dashboard.md
+        name: Build Using the XDS Dashboard
+      - url: part-1/create-app-build-ide.md
+        name: Build Using an IDE
     - name: Debug your first AGL application
       children:
       - url: part-1/5-1_debug-first-app-config.md
@@ -45,7 +41,7 @@ books:
       - url: part-1/5-3_debug-first-app-ide.md
         name: xds-gdb from command line
       - url: part-1/5_debug-first-app.md
-        name: xds-gdb within an IDE 
+        name: xds-gdb within an IDE
     - name: "X(cross) Development System: Internals"
       children:
       - url: part-2/0_Abstract.md
@@ -99,4 +95,4 @@ books:
         - url: part-2/4_xds-gdb/2_config.md
           name: Configuration
         - url: part-2/4_xds-gdb/3_debug.md
-          name: Debugging
-\ No newline at end of file
+          name: Debugging
diff --git a/docs/part-1/0_Abstract.md b/docs/part-1/0_Abstract.md
deleted file mode 100644
index e2620e6..0000000
--- a/docs/part-1/0_Abstract.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Getting Started for Users
-
-## Abstract
-
-X(cross) Development System (XDS) is set of tools that provide a multi-platform
-for cross development with near-zero installation.
-
-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 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:
-
-- 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
-- MacOS
-
-The following 3 main configurations are supported:
-
-- standalone (or local) config
-- On-Premise (local network)
-- SaaS (Cloud based)
-
-![](./pictures/xds-conf.png){:: style="width:98%;"}
diff --git a/docs/part-1/1-2_install-xds-server-vm.md b/docs/part-1/1-2_install-xds-server-vm.md
deleted file mode 100644
index 3bf2f61..0000000
--- a/docs/part-1/1-2_install-xds-server-vm.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Installation based on Virtual Machine appliance
-
-## Virtual Machine appliance prerequisites
-
-> VirtualBox is installed on the host machine
-
-please refer to [VirtualBox documentation](https://www.virtualbox.org/wiki/Downloads) for more details.
-
-## Get the appliance
-
-Load the pre-build AGL SDK appliance image including `xds-server`:
-
-```bash
-wget http://iot.bzh/download/public/XDS/appliance/xds-vm-debian9_latest.ova
-```
-
-## Clean old appliance
-
-You must have one and one xds appliance only.
-
-So, first remove the oldest xds appliance if needed.
-
-```bash
-# Get the virtual machine name
-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
-```
-
-## Create and start a new appliance
-
-Used provided script to create a new appliance or you can use 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 share folder to appliance, **mandatory** to 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
-```
-
-Start appliance
-
-```bash
-# Start XDS appliance
-[ -n ${VDS_VMNAME} ] && VBoxManage startvm ${VDS_VMNAME}
-```
-
-## Appliance settings
-
-This image exposes following network ports (NAT mode):
-
-- 8000 : `xds-server` to serve XDS basic web page
-- 2222 : ssh
-
-## Check if xds-server is running
-
-`xds-server` is automatically started as a service on container startup.
-
-To check if xds-server is correctly install and running, you can access the basic web page that gives you some instructions:
-
-```bash
-# if container/appliance 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.html)
diff --git a/docs/part-1/1_install-xds-server.md b/docs/part-1/1_install-xds-server.md
deleted file mode 100644
index 5b9f776..0000000
--- a/docs/part-1/1_install-xds-server.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Installing XDS server
-
-Depending of your configuration, this step is necessary or not.
-
-In other words **you are a developer and plan to use/connect to an existing `xds-server`**
-running on your local network (On-Premise config) or in the Cloud (SaaS config),
-**you don't need to install the server part and you can skip this step**.
-
-For others (standalone config or administrators that want to install an
-On-Premise solution) xds-server must be installed.
-
-Several installation types are supported:
-
-| Install type | Supported OS | Section to refer |
-|--------------|--------------|------------------|
-| Container | Linux or MacOS | [see Installation based on Docker container](./1-1_install-xds-server-docker.html) |
-| Virtual Machine | Linux, MacOS or Windows | [see Installation based on VirtualBox appliance](./1-2_install-xds-server-vm.html) |
-| Native | Linux | [see Native installation](./1-3_install-xds-server-native.html) |
diff --git a/docs/part-1/2_install-client.md b/docs/part-1/2_install-client.md
deleted file mode 100644
index 44906c0..0000000
--- a/docs/part-1/2_install-client.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Installing XDS client tools
-
-[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:
-
-- 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:
-
-- [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.
-
-## Install packages for debian distro type
-
-```bash
-# 'DISTRO' can be set to { xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, Debian_8.0, Debian_9.0 }
-export DISTRO="xUbuntu_16.04"
-
-# AGL_RELEASE can be set to {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-agent
-sudo apt-get install agl-xds-cli
-sudo apt-get install agl-xds-gdb
-```
-
-## Install packages for openSUSE distro type
-
-```bash
-# DISTRO can be set to {openSUSE_Leap_42.3, openSUSE_Leap_15.0, openSUSE_Tumbleweed}
-export DISTRO="openSUSE_Leap_15.0"
-
-# AGL_RELEASE can be set to {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-agent
-sudo zypper install agl-xds-cli
-sudo zypper install agl-xds-gdb
-```
-
-## Install for other platforms (Windows / MacOS)
-
-- Install `xds-agent`:
-
-  1. Download the latest released tarball from github [releases page](https://github.com/iotbzh/xds-agent/releases).
-
-  1. Then unzip the tarball any where into your local disk (for example: `/opt/AGL/xds` or `C:\AGL\xds`).
-
-  1. Add binary to PATH:
-
-      - MacOs: create the .bash_profile `nano .bash_profile` and add `export PATH="/opt/AGL/xds/xds-agent:$PATH`
-      - Windows: change the system path via control panel or system settings or
-    `setx path "C:\AGK\xds\xds-agent;%path%"`
-
-- repeat the previous steps to install other tools depending of your needs:
-  - `xds-cli` : requested for command line and IDE integration. ([released tarball link](https://github.com/iotbzh/xds-cli/releases)).
-  - `xds-gdb` : requested for debugging application. ([released tarball link](https://github.com/iotbzh/xds-gdb/releases)).
-
-## Start xds-agent
-
-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, `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
-
-# Get status and log of xds-agent service
-systemctl --user status xds-agent.service
-```
-
-On **MacOS** (or Linux), you can start-it manually using following commands:
-
-```batch
-/opt/AGL/bin/xds-agent
-```
-
-On **Windows**, you can start-it manually using following commands:
-
-```batch
-C:\AGL\xds\xds-agent\xds-agent.exe
-```
diff --git a/docs/part-1/4-1_build-first-app-setup.md b/docs/part-1/4-1_build-first-app-setup.md
deleted file mode 100644
index 7b8fff2..0000000
--- a/docs/part-1/4-1_build-first-app-setup.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Setup
-
-## Sources Sharing Methods
-
-### What are possible ways to share source trees ?
-
-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`.
-
-There are two possible methods to share sources between your host and the XDS server:
-- Cloud sync: implies your local directory will be sent to and replicated on the server. This method lets you clone project anywhere on your local disk,
-- Path mapping: apply when the xds-server is running locally. This method uses a volume shared between your host and the server, typically `$HOME/xds-workspace` directory. It is much more efficient as there is no replication onto the server ; but you must clone project under the shared directory (`$HOME/xds-workspace` is a good choice because it is shared by default. To create more shared volumes, See --volume option of [container creation script](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/xds/part-1/1-1_install-xds-server-docker.html#create-and-start-a-new-container) )
-
-### Which one should I choose ?
-
-It depends on your [deployment setup](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/xds/part-1/0_Abstract.html) (Standalone, On-Premise or SaaS).
-
-* Standalone : use local path mapping. It makes no sense to use cloud sync as it would add pointless overhead.
-* On-Premise : use Clound Sync.
-* SaaS : use Cloud Sync. This is the only way to achieve source sharing in this deployment setup.
-
-<!-- section-note -->
-**Note:** : [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) project is an AGL
-project based on [app-templates](https://git.automotivelinux.org/apps/app-templates/)
-(included as a git submodule). This CMake templating, used to develop application
-with the AGL Application Framework, will automatically generate makefile rules
-(eg. `remote-target-populate`) or scripts (eg. `build/target/xxx` scripts).
-
-For more info about app-template, please refer to [this documentation](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/sdk-devkit/docs/part-2/2_4-Use-app-templates.html).
-<!-- end-section-note -->
-
-## Clone project
-
-```bash
-cd $HOME/xds-workspace
-git clone --recursive https://github.com/iotbzh/helloworld-native-application.git
-```
diff --git a/docs/part-1/4-2_build-first-app-cmd.md b/docs/part-1/4-2_build-first-app-cmd.md
deleted file mode 100644
index c878d08..0000000
--- a/docs/part-1/4-2_build-first-app-cmd.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# Build using command line tool
-
-## Declare project
-
-Use XDS command line tool named [xds-cli](../part-2/3_xds-cli/0_abstract.html) to declare your
-project from command line and more precisely the `projects add` command
-(short option: `prj add`).
-
-```bash
-xds-cli prj add --label="Project_helloworld-native-application" --type=pm --path=/home/seb/xds-workspace/helloworld-native-application --server-path=/home/devel/xds-workspace/helloworld-native-application
-```
-
-> **Note:** option `--url=http://localhost:1234` may be added to `xds-cli` in
-> order to set url of `xds-agent` in case of agent is not running on default
-> port (for example here, 1234)
-
-## Build from command line
-
-You need to determine which is the unique id of your project. You can find
-this ID in project page of XDS dashboard or you can get it from command line
-using `xds-cli` tool and `projects list` command (short: `prj ls`):
-
-```bash
-xds-cli prj ls
-ID                                       Label                                   LocalPath
-f9904f70-d441-11e7-8c59-3c970e49ad9b     Project_helloworld-service              /home/seb/xds-workspace/helloworld-service
-4021617e-ced0-11e7-acd2-3c970e49ad9b     Project_helloworld-native-application   /home/seb/xds-workspace/helloworld-native-application
-```
-
-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.
-
-Now to refer your project, just use --id option or use `XDS_PROJECT_ID`
-environment variable.
-
-<!-- section-note -->
-**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
-<!-- end-section-note -->
-
-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:
-
-```bash
-xds-cli sdks ls
-List of installed SDKs:
-  ID                                    NAME
-  7aa19224-b769-3463-98b1-4c029d721766  aarch64  (3.99.1+snapshot)
-  41a1efc4-8443-3fb0-afe5-8313e0c96efd  corei7-64  (3.99.2+snapshot)
-  c226821b-b5c0-386d-94fe-19f807946d03  aarch64  (3.99.3)
-```
-
-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
-# First, grab your target IP address, or it's DNS name
-export TARGET_ADDRESS=<target_adress>
-
-# Go into your project directory and create a build directory
-cd $MY_PROJECT_DIR
-mkdir build
-
-# Generate build system using cmake
-# RSYNC_* variables must be set to allow deployment/populate widgets on target (see app-template doc for more info)
-xds-cli exec --id=4021617e --sdkid=c226821b -- "export RSYNC_TARGET=root@${TARGET_ADDRESS} ; export RSYNC_PREFIX=/opt ; cd build && cmake .."
-
-# Build the project
-xds-cli exec --id=4021617e --sdkid=c226821b -- "cd build && make widget"
-```
-
-<!-- section-note -->
-**Note:** If you use `&&`, `||` or `;` statement in the executed command line,
-you need to double quote the command, for example `"cd build && make`.
-<!-- end-section-note -->
-
-To avoid to set project id, sdks id, url, ... for each command line, you can
-define these settings as environment variables within an env file and just set
-`--config` option or source file before executing xds-cli command.
-
-Note that XDS creates a file named `xds-project.conf` (only if not already exists)
-when you declare a new project using XDS Dashboard (or using `xds-cli prj add...`).
-Edit this file if needed and then refer it with `--config` option.
-
-For example, the equivalence of above command is:
-
-```bash
-# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
-cd $MY_PROJECT_DIR
-
-# Edit and potentially adapt xds-project.conf file that has been created
-# automatically on project declaration using XDS Dashboard
-cat xds-project.conf
-  # XDS project settings
-  export XDS_AGENT_URL=localhost:8800
-  export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
-  export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03
-
-# Create build directory and invoke cmake and then build project
-xds-cli exec --config=./xds-project.conf -- "mkdir -p build && cd build && cmake .."
-cd build && xds-cli exec --config=../xds-project.conf -- "make all"
-
-# Or equivalent by first sourcing conf file (avoid to set --config option)
-source xds-project.conf
-xds-cli exec "mkdir -p build && cd build && cmake .."
-cd build && xds-cli exec "make all"
-```
-
-<!-- section-note -->
-**Note:** all parameters after a double dash (--) are considered as the command
-to execute.
-<!-- end-section-note -->
diff --git a/docs/part-1/4-3_build-first-app-dashboard.md b/docs/part-1/4-3_build-first-app-dashboard.md
deleted file mode 100644
index 076be94..0000000
--- a/docs/part-1/4-3_build-first-app-dashboard.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Build using XDS Dashboard
-
-## Declare project
-
-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`
-
-Open the right sidebar and select `Projects` entry to open project page and then
-create/declare a new project by with the plus icon:
-
-![](./pictures/xds-dashboard-icon-2.png){:: style="margin:auto; display:flex"}
-
-<!-- pagebreak -->
-
-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`.
-
-<!-- section-note -->
-**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](./1-1_install-xds-server-docker.html) ),
-the **Server Path** must be set to `/home/devel/xds-workspace/xxx` where xxx is your
-project directory name.
-
-If you select `Cloud Sync`, you can clone your project wherever you want on
-your local disk.
-<!-- end-section-note -->
-
-## Build from XDS dashboard
-
-<!-- section-note -->
-**Note:** _helloworld-native-application_ requires few configuration items to be able to walkthrough the whole process.
-To pass some environment variables, use the `Settings` window in the `Build` tab. The `Env variables` field allows to pass a list of environment variables (semi-colon separated) that will be set on the server prior to any build action.
-For the _helloworld-native-application_ you have to pass something like `RSYNC_TARGET=root@mytarget;RSYNC_PREFIX=/opt` (please replace `mytarget` by a valid target IP address or DNS name entry).
-<!-- end-section-note -->
-
-Open the build page build entry of left sidebar ![](./pictures/xds-dashboard-icon-3.png){:: style="display:inline; padding:0;"},
-
-then select your **Project** and the **Cross SDK** you want to use and click on
-**Clean / Pre-Build / Build / Populate** buttons to execute various build actions.
-
-![](./pictures/xds-dashboard-prj-2.png){:: style="width:90%; max-width:600px; margin:auto; display:flex"}
diff --git a/docs/part-1/4-4_build-first-app-ide.md b/docs/part-1/4-4_build-first-app-ide.md
deleted file mode 100644
index a3fa5a8..0000000
--- a/docs/part-1/4-4_build-first-app-ide.md
+++ /dev/null
@@ -1,194 +0,0 @@
-# Build using a source code editor / IDE
-
-First create an XDS config file or reuse the previous one, for example we use
-here aarch64 SDK to cross build application for a Renesas Gen3 board.
-
-```bash
-# create file at root directory of your project
-# for example:
-# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
-cat > $MY_PROJECT_DIR/xds-project.conf << EOF
- export XDS_AGENT_URL=localhost:8800
- export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
- export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03
-EOF
-```
-
-## NetBeans
-
-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
-**Run -> Set Project Configuration**.
-
-__Netbeans 8.x :__
-
-- Open menu **Tools** -> **Options**
-  - Open **C/C++** tab, in **Build Tools** sub-tab, click on **Add** button:
-
-    ![Add new tool panel](./pictures/nb_newtool.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
-
-  - Then, you should set **Make Command** and **Debugger Command** to point to xds tools:
-
-    ![Add new tool panel](./pictures/nb_xds_options.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
-
-  - Finally click on **OK** button.
-
-- Now create we first declare project into NetBeans and create first a native
-  configuration. To do that, open menu **File** -> **New Project**
-
-- Select **C/C++ Project with Existing Sources** ;
-  Click on **Next** button
-
-- Specify your project directory and set **Select Configuration Mode** to
-  **Custom**. Keep **Tool Collection** to **Default GNU** in order to create a
-  *native configuration* based on native GNU GCC. Finally click on **Next** button.
-
-    ![Select Model panel](./pictures/nb_new-project-1.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
-
-- Just update **Run in Folder** field and add `build_native` suffix so that
-  resulting build files will be located into `build_native` sub-directory.
-  Keep all others settings to default value and  click on **Next** button.
-
-    ![Select Model panel](./pictures/nb_new-project-2.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
-
-- Click several times on **Next button** (always keep default settings) and
-  click on **Finish** button to complete creation of native configuration.
-
-- Now we will create a **cross configuration** based on XDS tools.
-  Edit project properties (using menu **File** -> **Project Properties**) to add a new configuration that will use XDS to cross-compile your application for example for a Renesas Gen3 board.
-
-  - in **Build** category, click on **Manage Configurations** button and then **New** button to add a new configuration named for example "Gen3 board"
-
-    ![Select Build category](./pictures/nb_new-project-3.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
-
-  - Click on **Set Active** button
-
-  - Select **Pre-Build** sub-category, and set:
-    - Working Directory: `build_gen3`
-    - Command Line: `xds-cli exec -c ../xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ..`
-    - Pre-build First: `ticked`
-
-  - Select **Make** sub-category, and set:
-    - Working Directory: `build_gen3`
-    - Build Command: `xds-cli exec -c ../xds-project.conf -- make remote-target-populate`
-    - Clean Command: `xds-cli exec -c ../xds-project.conf -- make clean`
-
-    ![Select Make sub-category](./pictures/nb_new-project-4.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
-
-  - Select **Run** sub-category, and set:
-    - Run Command: `target/start-on-root@renesas-gen3.sh`
-    - Run Directory: `build-gen3`
-
-    ![Select Run  sub-category](./pictures/nb_new-project-5.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
-
-  - Click on **OK** button to save settings
-
-By changing configuration from **Default** to **Gen3 board**, you can now simply
-compile your helloworld application natively (**Default** configuration) or
-cross-compile your application through XDS for the Renesas Gen3 board
-(**Gen3 board** configuration).
-
-## Visual Studio Code
-
-Open your project in VS Code
-
-```bash
-cd $MY_PROJECT_DIR
-code . &
-```
-
-Add new tasks : press `Ctrl+Shift+P` and select the `Tasks: Configure Task`
-command and you will see a list of task runner templates.
-
-And define your own tasks, here is an example to build
-[helloworld-native-application](https://github.com/iotbzh/helloworld-native-application)
-AGL helloworld application based on cmake template.
-
-```json
-{
-    "version": "2.0.0",
-    "type": "shell",
-    "presentation": {
-        "reveal": "always"
-    },
-    "tasks": [
-        {
-            "label": "clean",
-            "type": "shell",
-            "command": "/bin/rm -rf ${workspaceFolder}/build/* && mkdir -p build && echo Cleanup done.",
-            "problemMatcher": []
-        },
-        {
-            "label": "pre-build",
-            "type": "shell",
-            "group": "build",
-            "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ../",
-            "problemMatcher": [
-                "$gcc"
-            ]
-        },
-        {
-            "label": "build",
-            "type": "shell",
-            "group": "build",
-            "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget",
-            "problemMatcher": [
-                "$gcc"
-            ]
-        },
-        {
-            "label": "populate",
-            "type": "shell",
-            "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget-target-install",
-            "problemMatcher": []
-        }
-    ]
-}
-```
-
-To run a task : press `Ctrl+Shift+P`, select the `Tasks: Run task` and then
-select for example `pre-build` to trigger pre-build task.
-
-> **Note:**
->
-> You can also add your own keybindings to trig above tasks, for example:
->
-> ```json
-> // Build
-> {
->   "key": "alt+f9",
->   "command": "workbench.action.tasks.runTask",
->   "args": "clean"
-> },
-> {
->   "key": "alt+f10",
->   "command": "workbench.action.tasks.runTask",
->   "args": "pre-build"
-> },
-> {
->   "key": "alt+f11",
->   "command": "workbench.action.tasks.runTask",
->   "args": "build"
-> },
-> {
->   "key": "alt+f12",
->   "command": "workbench.action.tasks.runTask",
->   "args": "populate"
-> },
-> ```
->
-> More details about VSC keybindings [here](https://code.visualstudio.com/docs/editor/tasks#_binding-keyboard-shortcuts-to-tasks)
->
-> More details about VSC tasks [here](https://code.visualstudio.com/docs/editor/tasks)
-
-## Qt Creator
-
-Please refer to [agl-hello-qml](https://github.com/radiosound-com/agl-hello-qml#clone--build-project) project.
-Thanks to Dennis for providing this useful example.
-
-## Others IDE
-
-*Coming soon...*
diff --git a/docs/part-1/5-2_debug-first-app-cmd.md b/docs/part-1/5-2_debug-first-app-cmd.md
index d35b4b2..4d2ca84 100644
--- a/docs/part-1/5-2_debug-first-app-cmd.md
+++ b/docs/part-1/5-2_debug-first-app-cmd.md
@@ -21,7 +21,7 @@ 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/):
+[cmake-apps-module](https://git.automotivelinux.org/src/cmake-apps-module/):
 
 ```bash
 # Go into your project directory (for example helloworld-native-application)
@@ -56,12 +56,12 @@ xds-gdb -x target/gdb-on-root@myTarget.ini
 
 <!-- section-note -->
 **Note:** : [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) project is an AGL
-project based on [app-templates](https://git.automotivelinux.org/apps/app-templates/)
-(included as a git submodule). This CMake templating, used to develop application
+project based on [cmake-apps-module](https://git.automotivelinux.org/src/cmake-apps-module/)
+(refer to install cmake module [instructions](../../cmakeafbtemplates/dev_guide/installing-cmake.html)). This CMake templating, used to develop application
 with the AGL Application Framework, will automatically generate makefile rules
 (eg. `remote-target-populate`) or scripts (eg. `build/target/xxx` scripts).
 
-For more info about app-template, please refer to [this documentation](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/sdk-devkit/docs/part-2/2_4-Use-app-templates.html).
+For more info about app-template, please refer to [this documentation](../../../#using-the-cmake-applications-module).
 <!-- end-section-note -->
 
 ## Native debugging
diff --git a/docs/part-1/client-part.md b/docs/part-1/client-part.md
new file mode 100644
index 0000000..b92cc0c
--- /dev/null
+++ b/docs/part-1/client-part.md
@@ -0,0 +1,143 @@
+# Client Part
+
+The client part of the X(cross) Development System (XDS) is
+a set of XDS client tools that must run on your development host.
+
+The tools that comprise the client part are: `xds-agent`, `xds-cli`, and `xds-gdb`.
+Of the three, only `xds-agent`, whose source code can be found
+[here](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/xds/xds-agent.git)
+in Gerrit is required.
+
+<!-- section-note -->
+**NOTE:**
+
+The binary version is also available as standard Linux packages
+or as a portable Windows archive (i.e. Zip).
+<!-- end-section-note -->
+
+You should establish the following chain:
+
+- XDS Client: (i.e. `xds-cli` or XDS Dashboard).
+- XDS Agent: (`xds-agent`) running on your development host.
+- XDS Server:  (`xds-server`) running on a remote server and/or in a container.
+
+HTTP and Websocket protocols establish exchanges between these three tools.
+
+You can change the default URL/port shown in the following illustration by using
+configuration files.
+
+![XDS blocks chain](./pictures/xds-block-chain.png)
+
+<!-- section-note -->
+**NOTE:**
+Installation of the XDS client tools `xds-cli` and `xds-gdb` is
+optional:
+
+- [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.
+<!-- end-section-note -->
+
+## Install Packages for Debian
+
+Use the following commands to install packages for the client part
+on Debian-based systems:
+
+```bash
+# Set DISTRO (e.g. xUbuntu_16.04, xUbuntu_16.10, xUbuntu_17.04, xUbuntu_18.04, Debian_8.0, Debian_9.0)
+export DISTRO="xUbuntu_18.04"
+
+# Set AGL_RELEASE (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-agent
+sudo apt-get install agl-xds-cli
+sudo apt-get install agl-xds-gdb
+```
+
+## Install Packages for OpenSUSE
+
+Use the following commands to install packages for the client part
+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-agent
+sudo zypper install agl-xds-cli
+sudo zypper install agl-xds-gdb
+```
+
+## Install Packages for Other Platforms (e.g. Windows / MacOS)
+
+- Follow these steps to install `xds-agent`:
+
+  1. Download the latest released tarball from the GitHub [Releases Page](https://github.com/iotbzh/xds-agent/releases).
+
+  1. Unzip the tarball anywhere into your local drive (e.g. `/opt/AGL/xds` or `C:\AGL\xds`).
+
+  1. Add binary to PATH:
+
+      - MacOs: create the .bash_profile `nano .bash_profile` and add `export PATH="/opt/AGL/xds/xds-agent:$PATH`
+      - Windows: change the system path using the control panel or system settings.
+        Alternatively, you can `setx path "C:\AGK\xds\xds-agent;%path%"`
+
+- If you want to install optional tools, repeat the previous steps for each tool:
+  - `xds-cli`, which is used for command-line and IDE integration.
+  Downloaded from the ([released tarball link](https://github.com/iotbzh/xds-cli/releases)).
+  - `xds-gdb`, used for debugging applications.
+  Downloaded from the ([released tarball link](https://github.com/iotbzh/xds-gdb/releases)).
+
+## Start xds-agent
+
+As noted earlier, the `xds-agent` client tool must run on your local
+development host when you use XDS.
+Depending on your development host, use the following commands:
+
+- For a Linux-based development host, a user systemd service is provided
+  (i.e. `xds-agent.service`).
+
+  To start this service automatically when your host boots, enable
+  the service using the following command:
+
+  ```bash
+  # Enable xds-agent service at boot
+  systemctl --user enable xds-agent.service
+  ```
+
+  To start the XDS-agent service and display its log, use these
+  commands:
+
+  ```bash
+  # Manually start xds-agent service
+  systemctl --user start xds-agent.service
+
+  # Get status and log of xds-agent service
+  systemctl --user status xds-agent.service
+  ```
+
+- For a MacOS-based host, use the following command to
+  manually start `xds-agent`:
+
+  ```batch
+  /opt/AGL/bin/xds-agent
+  ```
+
+- For a Windows-based host, use the following command to
+  manually start `xds-agent`:
+
+  ```batch
+  C:\AGL\xds\xds-agent\xds-agent.exe
+  ```
diff --git a/docs/part-1/create-app-build-cmd-line.md b/docs/part-1/create-app-build-cmd-line.md
new file mode 100644
index 0000000..5d81625
--- /dev/null
+++ b/docs/part-1/create-app-build-cmd-line.md
@@ -0,0 +1,171 @@
+# Build Using the Command Line
+
+One option for building your application using XDS is to use
+the command line (i.e. `xds-cli`).
+Building the application consists of declaring your project, identifying
+some key ID values, and then using the command line to build it.
+
+<!-- section-note -->
+**NOTE:**
+
+XDS tools, including `xds-cli`, are installed by default in
+the `/opt/AGL/bin` directory.
+During installation, this directory is automatically added to your
+`PATH` variable.
+If, for some reason, the tool is not in your `PATH` directory,
+you can manually add it using the `export PATH=${PATH}:/opt/AGL/bin`
+command.
+<!-- end-section-note -->
+
+
+## Declare Project
+
+Use the `projects add` command to declare your project:
+
+```bash
+xds-cli prj add --label="Project_helloworld-native-application" --type=pm --path=/home/seb/xds-workspace/helloworld-native-application --server-path=/home/devel/xds-workspace/helloworld-native-application
+```
+
+When you declare the project, XDS creates the `xds-project.conf`
+configuration file if one does not already exist.
+You should examine this configuration file before you build the
+project to be sure all configurations are correct for your project.
+
+<!-- section-note -->
+**NOTE:**
+
+If the Server Part (i.e. `xds-agent`) is not running on the default
+port, you can use the `--url=http://localhost:<port>` option with the
+`xds-cli prj add` command to specify the port.
+Just substitute the actual port for `<port>` with the option.
+<!-- end-section-note -->
+
+## Determine the ID of Your Project
+
+After declaring your project, you need to determine the
+unique ID of your project.
+
+From the command line, use the `prj ls` command, which is an abbreviation
+for the `projects list` command:
+
+```bash
+xds-cli prj ls
+ID                                       Label                                   LocalPath
+f9904f70-d441-11e7-8c59-3c970e49ad9b     Project_helloworld-service              /home/seb/xds-workspace/helloworld-service
+4021617e-ced0-11e7-acd2-3c970e49ad9b     Project_helloworld-native-application   /home/seb/xds-workspace/helloworld-native-application
+```
+
+Once you have the ID of the project, you can use the `--id` option
+or the `XDS_PROJECT_ID` environment variable to refer to your project.
+
+<!-- section-note -->
+**NOTE:**
+
+When using the project ID from the command line, you can use the "short"
+notation by providing a non-ambiguous portion of the ID.
+For example, to refer to the `Project_helloworld-native-application` project
+shown in the previous example, you can use `-id 40` rather than
+`--id 40 instead of --id 4021617e-ced0-11e7-acd2-3c970e49ad9b`.
+<!-- end-section-note -->
+
+## Determine the ID of Your SDK
+
+You also need to determine the ID of the SDK you want to use to cross-build
+your application.
+
+To list installed SDKs, use the following command:
+
+```bash
+xds-cli sdks ls
+List of installed SDKs:
+  ID                                    NAME
+  7aa19224-b769-3463-98b1-4c029d721766  aarch64  (3.99.1+snapshot)
+  41a1efc4-8443-3fb0-afe5-8313e0c96efd  corei7-64  (3.99.2+snapshot)
+  c226821b-b5c0-386d-94fe-19f807946d03  aarch64  (3.99.3)
+```
+
+SDK IDs are returned by architecture and version.
+Be sure to identify the SDK you need.
+
+## Build the Application
+
+You can now use XDS to cross-build your project.
+Following is an example that builds a project that is based on CMake:
+
+```bash
+# First, export the target IP address, or it's DNS name
+export TARGET_ADDRESS=<target_adress>
+
+# Go into your project directory and create a build directory
+cd $MY_PROJECT_DIR
+mkdir build
+```
+
+Before using the command line to build the project, you should be
+sure the project's configuration file is correct.
+Examine the `xds-project.conf` configuration file and edit it
+as needed.
+
+Generate the build system using CMake:
+
+```
+# You must set RSYNC_* variables so that you deploy and populate widgets on the target
+xds-cli exec --id=4021617e --sdkid=c226821b -- "export RSYNC_TARGET=root@${TARGET_ADDRESS} ; export RSYNC_PREFIX=/opt ; cd build && cmake .."
+```
+
+Now you can build the project:
+
+```
+xds-cli exec --id=4021617e --sdkid=c226821b -- "cd build && make widget"
+```
+
+<!-- section-note -->
+**NOTE:**
+
+If you use `&&`, `||` or `;` statements in the executed command line,
+you need to double quote the command (e.g. `"cd build && make"`).
+<!-- end-section-note -->
+
+To avoid having to set the project ID, SDK ID, and URL for each
+command line, you can define these settings as environment variables
+using an environment file.
+Use the `--config` option or source file before executing
+the `xds-cli` command.
+
+To specify your configuration file with the command line,
+use the `--config` option.
+For example, the equivalent of the previous build command but
+with a specified configuration file is as follows:
+
+```bash
+# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
+cd $MY_PROJECT_DIR
+
+# Edit and potentially adapt xds-project.conf file that has been created
+# automatically on project declaration using XDS Dashboard
+cat xds-project.conf
+  # XDS project settings
+  export XDS_AGENT_URL=localhost:8800
+  export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
+  export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03
+
+# Create build directory and invoke cmake and then build project
+xds-cli exec --config=./xds-project.conf -- "mkdir -p build && cd build && cmake .."
+cd build && xds-cli exec --config=../xds-project.conf -- "make all"
+```
+
+Alternatively, you could first source the configuration file to avoid using the
+`--config` option as follows:
+
+```
+source xds-project.conf
+xds-cli exec "mkdir -p build && cd build && cmake .."
+cd build && xds-cli exec "make all"
+```
+
+<!-- section-note -->
+**NOTE:**
+
+All parameters after a double dash (`--`) are considered as the command
+to execute.
+<!-- end-section-note -->
diff --git a/docs/part-1/create-app-build-dashboard.md b/docs/part-1/create-app-build-dashboard.md
new file mode 100644
index 0000000..d5d2dbb
--- /dev/null
+++ b/docs/part-1/create-app-build-dashboard.md
@@ -0,0 +1,93 @@
+# Build Using the XDS Dashboard
+
+One option for building your application using XDS is to use
+the XDS Dashboard.
+Building the application consists of using the dashboard
+to declare your project and then initiate the build.
+
+## Declare Project
+
+Follow these steps to declare the project:
+
+1. Open a Web Browser and connect to to the XDS Dashboard.
+
+   The URL you use depends of your configuration (e.g. `http://localhost:8800`).
+
+2. Open the right sidebar and select the `Projects` entry to open the
+   project page.
+   Once the page is open, declare a new project by clicking on the
+   "plus" icon next to "Add Project":
+
+   ![](./pictures/xds-dashboard-icon-2.png){:: style="margin:auto; display:flex"}
+
+   When you declare the project, XDS creates the `xds-project.conf`
+   configuration file if one does not already exist.
+   You should examine this configuration file before you build the
+   project to be sure all configurations are correct for your project.
+
+   The configuration file can be very useful when you plan to use
+   XDS client tools such as `xds-cli` or `xds-gdb`.
+
+   <!-- pagebreak -->
+
+3. Set `Sharing Type` appropriately depending on your Client Part
+   configuration:
+
+   ![](./pictures/xds-dashboard-prj-1.png){:: style="width:90%; max-width:560px; margin:auto; display:flex"}
+
+   <!-- section-note -->
+   **NOTES:**
+
+   - When `Path mapping` type is selected, you must clone your project into
+     `$HOME/xds-workspace` directory, which is named **Local Path** in the modal window.
+
+   - If XDS server is running in the XDS docker container
+     the **Server Path** must be set to `/home/devel/xds-workspace/<xxx>`
+     where `<xxx>` is your project directory name.
+     See the "[Installation based on Docker container](server-part.html#docker-container))"
+     section for more information.
+
+   - If you select `Cloud Sync`, you can clone your project wherever you want on
+     your local disk.
+   <!-- end-section-note -->
+
+## Build the Application
+
+Building the application requires opening the build page's "build entry" in the
+left navigational pane, selecting both the project and the SDK, and
+then initiating the build.
+
+<!-- section-note -->
+**NOTE:**
+
+To use the `helloworld-native-application` example, you need to provide
+some configuration items.
+Specifically, you must pass values for both the
+`RSYNC_TARGET` and `RSYNC_PREFIX` environment variables.
+To pass these variables, use the `Settings` window in the `Build` tab.
+You can use the `Env variables` field to pass a list of environment variables
+that are set on the server prior to the build occurring.
+You must separate individual variables using the semi-colon character:
+
+```
+RSYNC_TARGET=root@<mytarget>;RSYNC_PREFIX=/opt
+```
+
+When you pass these variables, substitute `<mytarget>` with the valid
+target IP address or DNS name entry.
+<!-- end-section-note -->
+
+Follow these steps to build the application:
+
+1. Open the build page build entry in the left-hand navigation pane:
+
+   ![](./pictures/xds-dashboard-icon-3.png){:: style="display:inline; padding:0;"},
+
+2. Select your **Project**.
+
+3. Seclect the **Cross SDK** you want to use.
+
+4. Click the **Clean / Pre-Build / Build / Populate** buttons to execute
+   the build action you want.
+
+   ![](./pictures/xds-dashboard-prj-2.png){:: style="width:90%; max-width:600px; margin:auto; display:flex"}
diff --git a/docs/part-1/create-app-build-ide.md b/docs/part-1/create-app-build-ide.md
new file mode 100644
index 0000000..cbf39f6
--- /dev/null
+++ b/docs/part-1/create-app-build-ide.md
@@ -0,0 +1,244 @@
+# Build using an IDE
+
+One option for building your application using XDS is to use
+an Integrated Development Environment
+([IDE](https://en.wikipedia.org/wiki/Integrated_development_environment)).
+Many IDEs exist (e.g. [NetBeans](https://netbeans.org/),
+[Visual Studio Code](https://code.visualstudio.com/),
+[Qt Creator](https://www.qt.io/),
+[Eclipse](https://www.eclipse.org/), and so forth).
+
+This section first develops an XDS configuration file
+(i.e. `xds-project.conf`) and then provides two
+examples, NetBeans and Visual Studio, that do the following.
+
+- NetBeans: Creates two separate build configurations
+  for a project, which makes it easy to switch back and forth
+  between types of builds.
+
+- Visual Studio: Creates tasks that allow you to build an example
+  based on CMake templates.
+
+## XDS Configuration File
+
+This section shows how to create an XDS configuration file
+(i.e. `xds-project.conf`) or how to re-use an existing file.
+For example, the following commands set up the configuration
+file for an `aarch64` SDK to cross-build the
+application for a Renesas Gen3 board.
+
+```bash
+# create file at root directory of your project
+# for example:
+# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
+cat > $MY_PROJECT_DIR/xds-project.conf << EOF
+ export XDS_AGENT_URL=localhost:8800
+ export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
+ export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03
+EOF
+```
+
+## NetBeans
+
+This section creates two configurations: one to compile the
+project natively using native GNU gcc, and one to cross-compile
+the project using XDS.
+
+Having two configurations allows you to easily switch between them
+using NetBean's **Run -> Set Project Configuration** menu.
+
+### Native Configuration
+
+Follow these steps to create the native configuration:
+
+1. Open the **Tools** -> **Options** menu.
+
+2. Open the **C/C++** tab.
+
+3. Click on the **Add** button in the **Build Tools** sub-tab:
+
+   ![Add new tool panel](./pictures/nb_newtool.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
+
+4. Fill the **Make Command** and **Debugger Command** fields to point to the XDS tools:
+
+   ![Add new tool panel](./pictures/nb_xds_options.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
+
+5. Click **OK**.
+
+6. Select the **File** -> **New Project** menu item to declare the
+   project and create a native configuration.
+
+7. Select **C/C++ Project with Existing Sources** and click on **Next**.
+
+8. Specify your project directory and set **Select Configuration Mode** to
+   "Custom".
+   Be sure to keep **Tool Collection** set to "Default GNU" in order to create a
+   *native configuration*, which is based on the native GNU GCC.
+
+9. Click **Next**.
+
+   ![Select Model panel](./pictures/nb_new-project-1.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
+
+10. Update the **Run in Folder** field to add the `build_native` suffix.
+    Doing so results in the build files being located in the
+    `build_native` sub-directory.
+    Be sure to keep the defaults for all other settings and then click **Next**.
+
+    ![Select Model panel](./pictures/nb_new-project-2.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
+
+11. Click through **Next** several times while always keeping the
+    default settings until the **Finish** button appears.
+
+12. Click **Finish** to complete the creation of the native configuration.
+
+### Cross-Compilation Configuration
+
+Follow these steps to create the configuration for cross-compilation
+based on the XDS tools:
+
+1. Edit project properties (using menu **File** -> **Project Properties**)
+   to add a new configuration that will use XDS to cross-compile
+   your application for example for a Renesas Gen3 board.
+
+2. in the **Build** category, click on **Manage Configurations** button
+   and then **New** button to add a new configuration named for example
+   "Gen3 board".
+
+   ![Select Build category](./pictures/nb_new-project-3.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
+
+3. Click the **Set Active** button.
+
+4. Select the **Pre-Build** sub-category, and set the following:
+
+   - Working Directory: `build_gen3`
+   - Command Line: `xds-cli exec -c ../xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ..`
+   - Pre-build First: `ticked`<br/><br/>
+
+5. Select the **Make** sub-category, and set the following:
+
+   - Working Directory: `build_gen3`
+   - Build Command: `xds-cli exec -c ../xds-project.conf -- make remote-target-populate`
+   - Clean Command: `xds-cli exec -c ../xds-project.conf -- make clean`<br/><br/>
+
+   ![Select Make sub-category](./pictures/nb_new-project-4.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
+
+6. Select the **Run** sub-category, and set the following:
+
+   - Run Command: `target/start-on-root@renesas-gen3.sh`
+   - Run Directory: `build-gen3`<br/><br/>
+
+   ![Select Run  sub-category](./pictures/nb_new-project-5.png){:: style="width:90%; max-width:700px; margin:auto; display:flex"}
+
+7. Click **OK** to save settings.
+
+By changing the configuration from **Default** to **Gen3 board**, you can
+compile your helloworld application natively, which is the default configuration.
+Or, you can cross-compile your application using XDS for the Renesas Gen3 board,
+which is the Gen3 board configuration.
+
+## Visual Studio Code
+
+This section presents a Visual Studio example that creates tasks
+that allow you to build an example that is based on CMake templates.
+
+Follow these steps:
+
+1. Start Visual Studio Code and open your project using the
+   following commands:
+
+   ```bash
+   cd $MY_PROJECT_DIR
+   code . &
+   ```
+
+2. Add new tasks by entering the `Ctrl+Shift+P` key combination and selecting
+   the `Tasks: Configure Task` command.
+   A list of task runner templates appears.
+
+3. Define your own tasks.
+   Following is an example that builds the
+   [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application)
+   that is based on CMake templates.
+
+   ```json
+   {
+       "version": "2.0.0",
+       "type": "shell",
+       "presentation": {
+           "reveal": "always"
+       },
+       "tasks": [
+           {
+               "label": "clean",
+               "type": "shell",
+               "command": "/bin/rm -rf ${workspaceFolder}/build/* && mkdir -p build && echo Cleanup done.",
+               "problemMatcher": []
+           },
+           {
+               "label": "pre-build",
+               "type": "shell",
+               "group": "build",
+               "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ../",
+               "problemMatcher": [
+                   "$gcc"
+               ]
+           },
+           {
+               "label": "build",
+               "type": "shell",
+               "group": "build",
+               "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget",
+               "problemMatcher": [
+                   "$gcc"
+               ]
+           },
+           {
+               "label": "populate",
+               "type": "shell",
+               "command": "/opt/AGL/bin/xds-cli exec --rpath build --config xds-project.conf -- make widget-target-install",
+               "problemMatcher": []
+           }
+       ]
+   }
+   ```
+
+4. Run a task by entering the `Ctrl+Shift+P` key combination and
+   selecting `Tasks: Run task` and then selecting the specific task.
+   For example, select `pre-build` to trigger pre-build task.
+
+5. Optionally add keybindings that trigger tasks.
+   Following is an example:
+
+   ```json
+   // Build
+   {
+     "key": "alt+f9",
+     "command": "workbench.action.tasks.runTask",
+     "args": "clean"
+   },
+   {
+     "key": "alt+f10",
+     "command": "workbench.action.tasks.runTask",
+     "args": "pre-build"
+   },
+   {
+     "key": "alt+f11",
+     "command": "workbench.action.tasks.runTask",
+     "args": "build"
+   },
+   {
+     "key": "alt+f12",
+     "command": "workbench.action.tasks.runTask",
+     "args": "populate"
+   },
+   ```
+
+   <!-- section-note -->
+   **NOTES:**
+
+   - You can find more details about Visual Source Code keybindings
+     [here](https://code.visualstudio.com/docs/editor/tasks#_binding-keyboard-shortcuts-to-tasks).
+
+   - You can find more details about Visual Source Code tasks
+     [here](https://code.visualstudio.com/docs/editor/tasks).
+   <!-- end-section-note -->
diff --git a/docs/part-1/create-app-get-source-files.md b/docs/part-1/create-app-get-source-files.md
new file mode 100644
index 0000000..7fca382
--- /dev/null
+++ b/docs/part-1/create-app-get-source-files.md
@@ -0,0 +1,81 @@
+# Get the Source Files
+
+XDS needs to be able to share your application source files.
+This section describes the options you have for sharing your
+files with the server running XDS.
+
+## Source Sharing Methods
+
+For this example, you will use the _helloworld-native-application_
+project.
+You must clone this project's repository into a directory that
+`xds-server` can access.
+
+Two methods exist:
+
+- If you Client Part is configured for SaaS (i.e. Cloud Sync), the local
+  directory into which you clone your application project is sent to
+  and replicated on the server running XDS.
+  This implies that you can use any local directory for your cloned
+  application repository.
+
+- If you `xds-server` is running locally, you can use path mapping.
+  Path mapping uses a volume shared between your development host and the server
+  that is running XDS.
+  The directory shared is `$HOME/xds-workspace`.
+ 
+  <!-- section-note -->
+  **NOTE:**
+
+  The path mapping method of sharing files is more efficient than
+  replicating the project on the XDS server.
+  However, you must clone the project under a directory that can be shared.
+  The most convenient directory is the default shared directory, which is
+  `$HOME/xds-workspace`.
+  
+  You could create additional shared volumes.
+  To create more shared volumes, See the
+  "[Create and Start a New Container](server-part.html#create-and-start-a-new-container)"
+  section.
+
+## Which File Sharing Method Should I Choose?
+
+The file sharing method you choose depends on the
+Client Part configuration (i.e. Standalone, On-Premise or SaaS).
+
+- Standalone uses local path mapping. With this configuration, it
+  makes no sense to use SaaS (Cloud Sync) as it adds unnecessary overhead.
+
+- On-Premise uses Cloud Sync.
+
+- SaaS also uses Cloud Sync. With this configuration, replicating the
+  application project files on the XDS server is the only way to achieve
+  file sharing.
+
+<!-- section-note -->
+**NOTE:**
+
+The
+[helloworld-native-application](https://github.com/iotbzh/helloworld-native-application)
+project is an AGL project that is based on CMake
+(i.e. [cmake-apps-module](https://git.automotivelinux.org/src/cmake-apps-module/)).
+For information on installing and using the CMake templates, see the
+"[Installing the CMake Templates](../../../../devguides/reference/cmakeafbtemplates/dev_guide/installing-cmake.html)"
+section.
+CMake templates, when used to develop applications
+with the AGL Application Framework, automatically generate Makefile rules
+(e.g. `remote-target-populate`) or scripts (e.g. `build/target/xxx` scripts).
+<!-- end-section-note -->
+
+## Clone project
+
+Now that you know where you are going to put your application files,
+you can clone the repository.
+In the following example, the local repository is cloned to the
+default shared directory assuming path mapping, which is for
+a Client Part Standalone configuration.
+
+```bash
+cd $HOME/xds-workspace
+git clone --recursive https://github.com/iotbzh/helloworld-native-application.git
+```
diff --git a/docs/part-1/create-app-overview.md b/docs/part-1/create-app-overview.md
new file mode 100644
index 0000000..567a0fe
--- /dev/null
+++ b/docs/part-1/create-app-overview.md
@@ -0,0 +1,27 @@
+# Overview #
+
+The application development workflow using XDS begins with
+making sure you have met all the
+[requirements](create-app-requirements.html) needed to
+use the tool.
+
+Once requirements are met, you have some options for
+[getting the application source files](create-app-get-source-files.html)
+together.
+These options depend on where the XDS Server part is
+running and which Client Part configuration you are using
+(i.e. Standalone, On-Premise, or SaaS).
+
+You can build the application several ways:
+
+- Use the XDS Client
+  [Command Line](create-app-build-cmd-line.html)
+- Use the XDS Client
+  [Dashboard](create-app-build-dashboard.html)
+- Use a third-party Interactive Development Environment
+  ([IDE](create-app-build-ide)) application
+  (e.g. NetBeans, Visual Studio, and so forth).
+
+The following figure overviews the XDS application development process:
+
+![](pictures/create-app-workflow.png){:: style="margin:auto; display:flex"}
diff --git a/docs/part-1/create-app-requirements.md b/docs/part-1/create-app-requirements.md
new file mode 100644
index 0000000..6282075
--- /dev/null
+++ b/docs/part-1/create-app-requirements.md
@@ -0,0 +1,27 @@
+# Requirements
+
+Before you can build your application using XDS, you need to be
+sure you have satisfied the requirements described in this section.
+
+- The agent is running locally on your machine.
+  For information about the agent and how to install it, see the
+  "[Client Part](client-part.html)" section.
+
+- The server is running locally in a docker container
+  or is accessible on your network
+  For information about the server and how to install it, see the
+  "[Server Part](server-part)" section.
+
+- one or more Software Development Kits (SDKs) are installed.
+  For information on installing an SDK, see the
+  "[AGL SDKs](install-sdk.html)" or
+  "[Download or Build Your SDK Installer](../../../../getting_started/reference/getting-started/app-workflow-sdk.html)"
+  sections.
+
+- Your XDS configuration is correct.
+  You can test this connection between the agent and the server
+  by opening the XDS Dashboard in a Web Browser and confirming
+  no error messages.
+  See the
+  "[Check if xds-server is Running](server-part.html#check-if-xds-server-is-running)"
+  section.
diff --git a/docs/part-1/3_install-sdks.md b/docs/part-1/install-sdk.md
index 094e547..50a8b10 100644
--- a/docs/part-1/3_install-sdks.md
+++ b/docs/part-1/install-sdk.md
@@ -1,16 +1,46 @@
-# Installing AGL SDKs
+# 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.
+To build your AGL services or AGL applications using XDS,
+you must install a Software Development Kit (SDK) that
+matches your target/board.
 
-A SDK is a package that includes all tools you need to cross-build and cross-debug your service/application.
+An SDK is a package that includes all the tools you need
+to cross-build and cross-debug your service or application.
+You install an SDK by running the SDK Installer.
 
-You can generate AGL SDK for the board you want to use or you can download
-a pre-packaged AGL SDK.
+You can build an AGL SDK Installer for your board or you can download
+a pre-built installer.
 
-## Install a new SDK from command line
+This section describes how you can download a pre-built SDK
+Installer using either the command line or the XDS Dashboard.
+For information on how to build an SDK Installer, see the
+"[Download or Build Your SDK Installer](../../../../getting_started/reference/getting-started/app-workflow-sdk.html)"
+section.
 
-Used `sdks` command of `xds-cli` tool to managed SDKs.
+<!-- section-note -->
+**NOTES:**
+- In order to use the command line or the XDS Dashboard
+  to download an SDK Installer, you must
+  have the XDS Client set up in your toolchain (i.e. 'xds-cli').
+  If you did not install 'xds-cli', see the
+  "[Client Part](client-part.html)" section for instruction on how
+  to install XDS UI.
+
+- See the
+  "[xds-server](../part-2/1_xds-server/0_abstract.html)" chapter
+  for more information on SDK management.
+<!-- end-section-note -->
+
+## Command Line Operations
+
+This section describes how to download and install an SDK,
+abort an installation, install an SDK from a local directory,
+and view all installed SDKs.
+
+### Download and Install an SDK Using the Command Line
+
+Use the following commands to choose and install a pre-built SDK
+Installer:
 
 ```bash
 # List all available SDKs
@@ -27,7 +57,7 @@ a0ae663d      poky-agl-corei7-64-3.99.1+snapshot              Installed       3.
 8c2f2841      AGL-release-dab-4.0.2-dragonboard-410c          Not Installed   4.0.2           aarch64
 ...
 
-# Install a SDK (downloaded + install)
+# Download and Install an SDK
 xds-cli sdks install d65fe750
 
 Installation of 'AGL-release-eel-latest-qemux86-64' SDK successfully started.
@@ -58,15 +88,45 @@ Each time you wish to use the SDK in a new shell session, you need to source the
  $ . /xdt/sdk/poky-agl/4.99.5/corei7-64/environment-setup-corei7-64-agl-linux
 
 SDK ID d65fe750-d3a7-38f5-83d8-3d3806054f8d successfully installed.
+```
 
+### Abort an Installation that is in Progress
 
-# Abort an installation that is in progress
+To abort an ongoing installation (i.e. the `xds-cli sdks install d65fe750`
+in this example), use
+the `ctrl-C` key sequence. `Ctrl-C` only stops the XDS Client (`xds-cli`).
+The download or installation process running in the background
+is not stopped.
+
+In such cases, the `xds-cli sdks ls` command results in an
+`Installing` appearing in the STATUS column for all running installations. 
+
+If for some reason you need to abort, use the `sdks abort` command:
+
+```bash
 xds-cli sdks abort -id d65fe750
+```
+
+### Install an SDK Using a Local SDK Package or File
 
-# Install a SDK (using a local SDK package/file)
+If you have an SDK Installer that is already local to your system,
+you can use the command line to install it from your local directory:
+
+```bash
 xds-cli sdks install --file $HOME/xds-workspace/sdks/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-corei7-64-toolchain-4.99.5.sh
+```
+
+<!-- section-note -->
+**NOTE:**
+Installation based on a local SDK Installer is only supported when the
+SDK Installer is in the `$HOME/xds-workspace/sdks` directory.
+<!-- end-section-note -->
 
-# List installed SDKs
+### List Installed SDKs
+
+To list the installed SDKs, use the following command:
+
+```bash
 xds-cli sdks ls
 
 List of installed SDKs:
@@ -75,30 +135,30 @@ e45ac787 AGL-corei7-64-4.99.5+snapshot                   Installed       4.99.5
 d65fe750 AGL-release-eel-latest-qemux86-64               Installed       4.99.3  corei7-64
 ```
 
-<!-- section-note -->
-Installation based on a local SDK package is only supported when SDK file package
-is located in `$HOME/xds-workspace/sdks` directory
-<!-- end-section-note -->
-
-## Install a new SDK from XDS Dashboard
+## Install an SDK Using the XDS Dashboard
 
-Open XDS-Dashboard in web-browser and select `SDKs` entry in left side menu.
+Follow these steps to locate, download, and install an SDK
+using the XDS Dashboard:
 
-Then switch to `SDKs MANAGEMENT` view :
+1. Open the XDS Dashboard in a Web Browser and select
+   `SDKs` in left-hand menu.
 
-![](../part-1/pictures/xds-dashboard-sdks-mgt.png){:: style="margin:auto; display:flex"}
+2. Switch to `SDKs MANAGEMENT` view.
+   Following is an example:
 
-Use filter boxes to find the SDK you want to install and then click on plus
-icon (Actions column) to start installation.
+   ![](../part-1/pictures/xds-dashboard-sdks-mgt.png){:: style="margin:auto; display:flex"}
 
-SDK download and installation process may take several minutes and output of installation script (output of
-`add` script mentioned in above chapter).
+3. Use filter boxes to find the SDK you want to install.
 
-![](../part-1/pictures/xds-dashboard-sdks-install.png){:: style="margin:auto; display:flex"}
+4. Click on the "plus" icon in the "Actions" column to
+   start the installation.
 
-Note that you can abort installation by clicking on `CANCEL` button.
+   The SDK Installer downloads and the installation process begins.
+   In can take several minutes for the installation to complete.
+   Following is an example of the output:
 
-## More info
+   ![](../part-1/pictures/xds-dashboard-sdks-install.png){:: style="margin:auto; display:flex"}
 
-Please refer to [xds-server](../part-2/1_xds-server/0_abstract.html) chapter for more details
-about SDKs management.
+**NOTE:**<\br>
+If for some reason you need to abort an ongoing SDK installation,
+you can do so by clicking the `CANCEL` button.
diff --git a/docs/part-1/pictures/create-app-workflow.png b/docs/part-1/pictures/create-app-workflow.png
new file mode 100644
index 0000000..7784063
--- /dev/null
+++ b/docs/part-1/pictures/create-app-workflow.png
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
+```
+
diff --git a/docs/part-1/xds-overview.md b/docs/part-1/xds-overview.md
new file mode 100644
index 0000000..69a89ce
--- /dev/null
+++ b/docs/part-1/xds-overview.md
@@ -0,0 +1,56 @@
+# Overview
+
+X(cross) Development System (XDS) is set of tools that provides
+multi-platform cross development with
+[near-zero](https://en.wikipedia.org/wiki/Zero_Install)
+installation.
+
+This guide is available in two forms: the online version and a PDF
+version:
+
+- Online: [http://docs.automotivelinux.org/docs/en/guppy/devguides/#xcross-development-system-user's-guide](http://docs.automotivelinux.org/docs/en/guppy/devguides/#xcross-development-system-user's-guide)
+
+- PDF: [http://iot.bzh/download/public/XDS/docs/XDS_UsersGuide.pdf](http://iot.bzh/download/public/XDS/docs/XDS_UsersGuide.pdf)
+
+XDS has two goals:
+
+1. Provide a multi-platform, cross development
+tool with near-zero installation.
+
+2. Keep application source files local to the user's machine, which
+   makes XDS compatible with existing IT policies
+   (e.g. corporate backup or SCM), and lets users continue to work
+   using their favorite editors all while keeping performance during
+   editing and browsing activities.
+
+The following illustration shows XDS as two functional blocks:
+the client part and the server part.
+
+The client part consists of several tools some essential and some
+required.
+The client part must have `xds-agent` and can optionally have `xds-cli`
+and `xds-gdb`.
+The client part runs on the user's machine (Development Host).
+
+The server part (`xds-server`) can run anywhere in a container,
+which includes a standalone machine, a server machine connected
+through a local network, or a server machine connected through the Cloud.
+
+![](./pictures/xds-block-diagram.png){:: style="width:98%;"}
+
+<!-- pagebreak -->
+
+The client part is portable and can run on the following platforms:
+
+- Linux
+- Windows
+- MacOS
+
+The following figure shows the three supported configurations for the client part:
+
+- standalone (i.e. local)
+- On-Premise, which uses a local network
+- [Software as a Service](https://en.wikipedia.org/wiki/Software_as_a_service)
+  (SaaS), which is Cloud-based
+
+![](./pictures/xds-conf.png){:: style="width:98%;"}
diff --git a/docs/part-2/1_xds-server/3_how-to-run.md b/docs/part-2/1_xds-server/3_how-to-run.md
index 4e56f3f..88fda21 100644
--- a/docs/part-2/1_xds-server/3_how-to-run.md
+++ b/docs/part-2/1_xds-server/3_how-to-run.md
@@ -5,7 +5,7 @@
 been integrated into AGL SDK docker container.
 
 >**Note:** For more info about AGL SDK docker container, please refer to
-[AGL SDK Quick Setup](http://docs.automotivelinux.org/docs/getting_started/en/dev/reference/setup-sdk-environment.html)
+[AGL SDK Quick Setup](../../../../../getting_started/reference/getting-started/docker-container-setup.html)
 
 ## Start xds-server
author	Scott Rifenbark <srifenbark@gmail.com>	2019-04-11 15:31:33 +0200
committer	Scott Rifenbark <srifenbark@gmail.com>	2019-05-20 15:18:42 -0700
commit	3635b88a18de43bbdd2373259ac65c02bc63c139 (patch)
tree	d3f83a07a32230b938b700cc59419c8c85f42282
parent	8e5d6918c1a51ae3e948b95c30a357c700821e39 (diff)