From 781fce71d4b78c0edfc489e4093d082f271a234f Mon Sep 17 00:00:00 2001 From: Sebastien Douheret Date: Tue, 9 Oct 2018 10:45:08 +0200 Subject: Improves documentation * Describes better available source tree sharing method (between xds-agent and xds-server), and which to prefer depending on the deployment setup. * Gives indication about how to pass RSYNC_TARGET and RSYNC_PREFIX env vars to the helloworld-native-application build process. * Swap chapter order (build before config) Bug: SPEC-1993 Change-Id: Ie4c22f277a59b0405744d71b0fadff67c5d5d025 Signed-off-by: Sebastien Douheret --- docs/part-2/2_xds-agent/0_abstract.md | 6 +-- docs/part-2/2_xds-agent/1_build.md | 90 +++++++++++++++++++++++++++++++++++ docs/part-2/2_xds-agent/1_config.md | 47 ------------------ docs/part-2/2_xds-agent/2_config.md | 47 ++++++++++++++++++ docs/part-2/2_xds-agent/2_start.md | 52 -------------------- docs/part-2/2_xds-agent/3_build.md | 90 ----------------------------------- docs/part-2/2_xds-agent/3_start.md | 52 ++++++++++++++++++++ 7 files changed, 192 insertions(+), 192 deletions(-) create mode 100644 docs/part-2/2_xds-agent/1_build.md delete mode 100644 docs/part-2/2_xds-agent/1_config.md create mode 100644 docs/part-2/2_xds-agent/2_config.md delete mode 100644 docs/part-2/2_xds-agent/2_start.md delete mode 100644 docs/part-2/2_xds-agent/3_build.md create mode 100644 docs/part-2/2_xds-agent/3_start.md (limited to 'docs/part-2/2_xds-agent') diff --git a/docs/part-2/2_xds-agent/0_abstract.md b/docs/part-2/2_xds-agent/0_abstract.md index d73bdb9..b867d89 100644 --- a/docs/part-2/2_xds-agent/0_abstract.md +++ b/docs/part-2/2_xds-agent/0_abstract.md @@ -13,7 +13,7 @@ used to remotely cross build applications. Links to subchapters : -- [Configuration](./1_config.html) -- [Start-up](./2_start.html) -- [Build from scratch](./3_build.html) +- [Build from scratch](./1_build.html) +- [Configuration](./2_config.html) +- [Start-up](./3_start.html) - [Debugging](./4_debug.html) diff --git a/docs/part-2/2_xds-agent/1_build.md b/docs/part-2/2_xds-agent/1_build.md new file mode 100644 index 0000000..842f582 --- /dev/null +++ b/docs/part-2/2_xds-agent/1_build.md @@ -0,0 +1,90 @@ +# Build xds-agent from scratch + +## Dependencies + +Install [Go](https://golang.org/doc/install), [npm](https://www.npmjs.com/), +[nodejs](https://nodejs.org/en/) and some other tools. + +Refer to [Prerequisites chapter](../1_Prerequisites.html) for more details. + +## Building + +Clone sources under `$ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds/xds-agent` +in order respect directory hierarchy that match Go package import logic (see +[How to Write Go Code](https://golang.org/doc/code.html) for more details). + +Then use delivered Makefile : + +```bash +# Declare ROOTDIR, can be any location (for example xds-build) +ROOTDIR=$HOME/xds-build + +# Create directory hierarchy that match Go package import logic +mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds +cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds + +# Clone sources +git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-agent +# or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-agent + +# Build xds-agent +# (note that GOPATH will correctly be set by Makefile) +cd xds-agent +make all +``` + +Generate xds-agent packages / tarballs for Linux, MacOS, Windows + +```bash +make package-all +``` + +And to install `xds-agent` (by default in `/opt/AGL/xds/agent`): + +```bash +make install +``` + + +**Warning:** + +Makefile install rule and default values in configuration file are set +to fit the docker setup. + +So you may need to adapt some settings when you want to install xds-agent natively. + + + +**Note:** + +Used `DESTDIR` to specify another install directory + +```bash +make install DESTDIR=$HOME/opt/xds-agent +``` + + + +### Cross build + +For example on a Linux machine to cross-build for Windows, just follow these steps. + +The first time you need to install all the windows-amd64 standard packages on +your system with + +```bash +# List all supported OS / ARCH +go tool dist list + +# Install all standard packages for another OS/ARCH (eg. windows amd64) +GOOS=windows GOARCH=amd64 go install -v -a std +``` + +Then compile and package xds-agent using provided makefile + +```bash +export GOOS=windows +export GOARCH=amd64 +make all +make package +``` diff --git a/docs/part-2/2_xds-agent/1_config.md b/docs/part-2/2_xds-agent/1_config.md deleted file mode 100644 index 9e912cb..0000000 --- a/docs/part-2/2_xds-agent/1_config.md +++ /dev/null @@ -1,47 +0,0 @@ -# Configuration - -xds-agent configuration is driven by a JSON config file. - -The tarball mentioned in previous section includes this file with default settings. - -Here is the logic to determine which conf file will be used: - -1. from command line option: `--config myConfig.json` -1. `$HOME/.xds/agent/agent-config.json` file -1. `/etc/xds/agent/agent-config.json` file - -Supported fields in configuration file are (all fields are optional and example -below corresponds to the default values): - -- **httpPort** : http port of agent REST interface -- **webAppDir** : location of client webapp / dashboard (default: webapp/dist) -- **logsDir** : directory to store logs (eg. syncthing output) -- **xdsServers** : an array of xds-server object - - **xdsServers.url**: url of xds-server to connect to -- **syncthing**: a object defining syncthing settings - - **syncthing.binDir** : syncthing binaries directory (default: executable directory) - - **syncthing.home"** : syncthing home directory (usually .../syncthing-config) - - **syncthing.gui-address** : syncthing gui url (default ) - - **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated) - -```json -{ - "httpPort": "8800", - "webAppDir": "./www", - "logsDir": "${HOME}/.xds/agent/logs", - "xdsServers": [ - { - "url": "http://localhost:8000" - } - ], - "syncthing": { - "home": "${HOME}/.xds/agent/syncthing-config", - "gui-address": "http://localhost:8386", - "gui-apikey": "1234abcezam" - } -} -``` - ->**Note:** -> ->environment variables are supported by using `${MY_VAR}` syntax. diff --git a/docs/part-2/2_xds-agent/2_config.md b/docs/part-2/2_xds-agent/2_config.md new file mode 100644 index 0000000..9e912cb --- /dev/null +++ b/docs/part-2/2_xds-agent/2_config.md @@ -0,0 +1,47 @@ +# Configuration + +xds-agent configuration is driven by a JSON config file. + +The tarball mentioned in previous section includes this file with default settings. + +Here is the logic to determine which conf file will be used: + +1. from command line option: `--config myConfig.json` +1. `$HOME/.xds/agent/agent-config.json` file +1. `/etc/xds/agent/agent-config.json` file + +Supported fields in configuration file are (all fields are optional and example +below corresponds to the default values): + +- **httpPort** : http port of agent REST interface +- **webAppDir** : location of client webapp / dashboard (default: webapp/dist) +- **logsDir** : directory to store logs (eg. syncthing output) +- **xdsServers** : an array of xds-server object + - **xdsServers.url**: url of xds-server to connect to +- **syncthing**: a object defining syncthing settings + - **syncthing.binDir** : syncthing binaries directory (default: executable directory) + - **syncthing.home"** : syncthing home directory (usually .../syncthing-config) + - **syncthing.gui-address** : syncthing gui url (default ) + - **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated) + +```json +{ + "httpPort": "8800", + "webAppDir": "./www", + "logsDir": "${HOME}/.xds/agent/logs", + "xdsServers": [ + { + "url": "http://localhost:8000" + } + ], + "syncthing": { + "home": "${HOME}/.xds/agent/syncthing-config", + "gui-address": "http://localhost:8386", + "gui-apikey": "1234abcezam" + } +} +``` + +>**Note:** +> +>environment variables are supported by using `${MY_VAR}` syntax. diff --git a/docs/part-2/2_xds-agent/2_start.md b/docs/part-2/2_xds-agent/2_start.md deleted file mode 100644 index c537c93..0000000 --- a/docs/part-2/2_xds-agent/2_start.md +++ /dev/null @@ -1,52 +0,0 @@ -# Start-up - -## Start-up based on systemd user service - -For **Linux** distro, XDS agent can be started as a user service by Systemd. - -```bash -/usr/lib/systemd/user/xds-agent.service -``` - -Use well-known systemd commands to control `xds-agent.service` service. - -```bash -# Status XDS agent: -systemctl --user status xds-agent - -# Start XDS agent -systemctl --user start xds-agent - -# Stop XDS agent -systemctl --user stop xds-agent -``` - -Default settings are defined in `/etc/default/xds-agent` file but these -settings you can overwritten by `$HOME/.xds/agent/agent-config.json` file, -see [Configuration chapter](./1_config.html) for more details. - -## Manual start-up - -On **Linux or MacOS**, simply execute `xds-agent` executable: - -```bash -/opt/AGL/bin/xds-agent -``` - -On **Windows**, simply execute `xds-agent` executable (root path may change -depending where you installed/unzipped xds-agent tarball): - -```batch -C:\AGL\bin\xds-agent.exe -``` - - -**Note:** - -If need be, you can increase log level by setting option -`--log `, supported *level* are: panic, fatal, error, warn, info, debug. - -Invoke `xds-agent --help` to get more details about possible options that allow -for example to change logging level or select a specific configuration file. - - diff --git a/docs/part-2/2_xds-agent/3_build.md b/docs/part-2/2_xds-agent/3_build.md deleted file mode 100644 index 842f582..0000000 --- a/docs/part-2/2_xds-agent/3_build.md +++ /dev/null @@ -1,90 +0,0 @@ -# Build xds-agent from scratch - -## Dependencies - -Install [Go](https://golang.org/doc/install), [npm](https://www.npmjs.com/), -[nodejs](https://nodejs.org/en/) and some other tools. - -Refer to [Prerequisites chapter](../1_Prerequisites.html) for more details. - -## Building - -Clone sources under `$ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds/xds-agent` -in order respect directory hierarchy that match Go package import logic (see -[How to Write Go Code](https://golang.org/doc/code.html) for more details). - -Then use delivered Makefile : - -```bash -# Declare ROOTDIR, can be any location (for example xds-build) -ROOTDIR=$HOME/xds-build - -# Create directory hierarchy that match Go package import logic -mkdir -p $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds -cd $ROOTDIR/src/gerrit.automotivelinux.org/gerrit/src/xds - -# Clone sources -git clone https://gerrit.automotivelinux.org/gerrit/src/xds/xds-agent -# or git clone ssh://YOUR_USERNAME@gerrit.automotivelinux.org:29418/src/xds/xds-agent - -# Build xds-agent -# (note that GOPATH will correctly be set by Makefile) -cd xds-agent -make all -``` - -Generate xds-agent packages / tarballs for Linux, MacOS, Windows - -```bash -make package-all -``` - -And to install `xds-agent` (by default in `/opt/AGL/xds/agent`): - -```bash -make install -``` - - -**Warning:** - -Makefile install rule and default values in configuration file are set -to fit the docker setup. - -So you may need to adapt some settings when you want to install xds-agent natively. - - - -**Note:** - -Used `DESTDIR` to specify another install directory - -```bash -make install DESTDIR=$HOME/opt/xds-agent -``` - - - -### Cross build - -For example on a Linux machine to cross-build for Windows, just follow these steps. - -The first time you need to install all the windows-amd64 standard packages on -your system with - -```bash -# List all supported OS / ARCH -go tool dist list - -# Install all standard packages for another OS/ARCH (eg. windows amd64) -GOOS=windows GOARCH=amd64 go install -v -a std -``` - -Then compile and package xds-agent using provided makefile - -```bash -export GOOS=windows -export GOARCH=amd64 -make all -make package -``` diff --git a/docs/part-2/2_xds-agent/3_start.md b/docs/part-2/2_xds-agent/3_start.md new file mode 100644 index 0000000..d750fac --- /dev/null +++ b/docs/part-2/2_xds-agent/3_start.md @@ -0,0 +1,52 @@ +# Start-up + +## Start-up based on systemd user service + +For **Linux** distro, XDS agent can be started as a user service by Systemd. + +```bash +/usr/lib/systemd/user/xds-agent.service +``` + +Use well-known systemd commands to control `xds-agent.service` service. + +```bash +# Status XDS agent: +systemctl --user status xds-agent + +# Start XDS agent +systemctl --user start xds-agent + +# Stop XDS agent +systemctl --user stop xds-agent +``` + +Default settings are defined in `/etc/default/xds-agent` file but these +settings you can overwritten by `$HOME/.xds/agent/agent-config.json` file, +see [Configuration chapter](./2_config.html) for more details. + +## Manual start-up + +On **Linux or MacOS**, simply execute `xds-agent` executable: + +```bash +/opt/AGL/bin/xds-agent +``` + +On **Windows**, simply execute `xds-agent` executable (root path may change +depending where you installed/unzipped xds-agent tarball): + +```batch +C:\AGL\bin\xds-agent.exe +``` + + +**Note:** + +If need be, you can increase log level by setting option +`--log `, supported *level* are: panic, fatal, error, warn, info, debug. + +Invoke `xds-agent --help` to get more details about possible options that allow +for example to change logging level or select a specific configuration file. + + -- cgit