README.md

   1 # XDS - X(cross) Development System Server
   2
   3 `xds-server` is a web server that allows user to remotely cross build applications.
   4
   5 The first goal is to provide a multi-platform cross development tool with
   6 near-zero installation.
   7 The second goal is to keep application sources locally (on user's machine) to
   8 make it compatible with existing IT policies (e.g. corporate backup or SCM),
   9 and let user to continue to work as usual (use his favorite editor,
  10 keep performance while editing/browsing sources).
  11
  12 This powerful and portable webserver (written in [Go](https://golang.org))
  13 exposes a REST interface over HTTP and also provides a Web dashboard to configure projects and execute _(for now)_ only basics commands.
  14
  15 `xds-server` uses [Syncthing](https://syncthing.net/) tool to synchronize
  16 projects files from user machine to build server machine or container.
  17
  18 > **NOTE**: For now, only Syncthing sharing method is supported to synchronize
  19 projects files. But in a near future and for restricted configurations, `xds-server`
  20 will also support "standard" folder sharing (eg. nfs mount points or docker
  21 volumes).
  22
  23 > **SEE ALSO**: [xds-exec and xds-make](https://github.com/iotbzh/xds-make),
  24 wrappers on `exec` and `make` commands that allows you to send command to
  25 `xds-server` and consequently build your application from command-line or from
  26 your favorite IDE (eg. Netbeans or Visual Studio Code) through `xds-server`.
  27
  28 ## How to run
  29
  30 `xds-server` has been designed to easily compile and debug
  31 [AGL](https://www.automotivelinux.org/) applications. That's why `xds-server` has
  32 been integrated into AGL SDK docker container.
  33
  34 >**NOTE** For more info about AGL SDK docker container, please refer to
  35 [AGL SDK Quick Setup](http://docs.automotivelinux.org/docs/getting_started/en/dev/reference/setup-sdk-environment.html)
  36
  37 ### Get the container
  38
  39 Load the pre-build AGL SDK docker image including `xds-server`:
  40 ```bash
  41 wget -O - http://iot.bzh/download/public/2017/XDS/docker/docker_agl_worker-xds-latest.tar.xz | docker load
  42 ```
  43
  44 ### Start xds-server within the container
  45
  46 Use provided script to create a new docker image and start a new container:
  47 ```bash
  48 > wget https://raw.githubusercontent.com/iotbzh/xds-server/master/scripts/xds-docker-create-container.sh
  49 > bash ./xds-docker-create-container.sh 0 docker.automotivelinux.org/agl/worker-xds:3.99.1
  50
  51 > docker ps
  52 CONTAINER ID        IMAGE                                               COMMAND                  CREATED              STATUS              PORTS                                                                                         NAMES
  53 b985d81af40c        docker.automotivelinux.org/agl/worker-xds:3.99.1       "/usr/bin/wait_for..."   6 days ago           Up 4 hours          0.0.0.0:8000->8000/tcp, 0.0.0.0:69->69/udp, 0.0.0.0:10809->10809/tcp, 0.0.0.0:2222->22/tcp    agl-worker-seb-laptop-0-seb
  54 ```
  55
  56 This container exposes following ports:
  57   - 8000 : `xds-server` to serve XDS Dashboard
  58   - 69   : TFTP
  59   - 2222 : ssh
  60
  61 `xds-server` is automatically started as a service on container startup.
  62 If needed you can stop / start it manually using following commands:
  63 ```bash
  64 > ssh -p 2222 devel@localhost
  65
  66 [15:59:58] devel@agl-worker-seb-laptop-0-seb:~$ /usr/local/bin/xds-server-stop.sh
  67
  68 [15:59:58] devel@agl-worker-seb-laptop-0-seb:~$ /usr/local/bin/xds-server-start.sh
  69 ```
  70
  71 On `xds-server` startup, you should get the following output:
  72 ```
  73 ### Configuration in config.json:
  74 {
  75     "webAppDir": "/usr/local/bin/www-xds-server",
  76     "shareRootDir": "/home/devel/.xds/share",
  77     "logsDir": "/tmp/xds-server/logs",
  78     "sdkRootDir": "/xdt/sdk",
  79     "syncthing": {
  80         "binDir": "/usr/local/bin",
  81         "home": "/home/devel/.xds/syncthing-config",
  82         "gui-address": "http://localhost:8384",
  83         "gui-apikey": "1234abcezam"
  84     }
  85 }
  86
  87 ### Start XDS server
  88 nohup /usr/local/bin/xds-server --config /home/devel/.xds/config.json -log warn > /tmp/xds-server/logs/xds-server.log 2>&1
  89 pid=22379
  90 ```
  91
  92 >**NOTE:** You can set LOGLEVEL env variable to increase log level if you need it.
  93 > For example, to set log level to "debug" mode : ` LOGLEVEL=debug /usr/local/bin/xds-server-start.sh`
  94
  95 ### Install SDK cross-toolchain
  96
  97 `xds-server` uses cross-toolchain install into directory pointed by `sdkRootDir` setting (see configuration section below for more details).
  98 For now, you need to install manually SDK cross toolchain. There are not embedded into docker image by default because the size of these tarballs is too big.
  99
 100 Use provided `install-agl-sdks` script, for example to install SDK for ARM64:
 101
 102 ```bash
 103 /usr/local/bin/xds-utils/install-agl-sdks.sh --aarch aarch64
 104 ```
 105
 106 ### XDS Dashboard
 107
 108 `xds-server` serves a web-application (default port 8000:
 109 [http://localhost:8000](http://localhost:8000) ). So you can now connect your browser to this url and use what we call the **XDS dashboard**.
 110
 111 Then follow instructions provided by this dashboard, knowing that the first time
 112 you need to download and start `xds-agent` on your local machine. To download
 113 this tool, just click on download icon in dashboard configuration page or download one of `xds-agent` released tarball: [https://github.com/iotbzh/xds-agent/releases](https://github.com/iotbzh/xds-agent/releases).
 114
 115 See also `xds-agent` [README file](https://github.com/iotbzh/xds-agent) for more
 116 details.
 117
 118
 119 ## Build xds-server from scratch
 120
 121 ### Dependencies
 122
 123 - Install and setup [Go](https://golang.org/doc/install) version 1.7 or
 124 higher to compile this tool.
 125 - Install [npm](https://www.npmjs.com/) : `sudo apt install npm`
 126 - Install [gulp](http://gulpjs.com/) : `sudo npm install -g gulp-cli`
 127
 128 ### Building
 129
 130 Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile:
 131 ```bash
 132  mkdir -p $GOPATH/src/github.com/iotbzh
 133  cd $GOPATH/src/github.com/iotbzh
 134  git clone https://github.com/iotbzh/xds-server.git
 135  cd xds-server
 136  make all
 137 ```
 138
 139 And to install `xds-server` (by default in `/usr/local/bin`):
 140 ```bash
 141 make install
 142 ```
 143
 144 >**NOTE:** Used `DESTDIR` to specify another install directory
 145 >```bash
 146 >make install DESTDIR=$HOME/opt/xds-server
 147 >```
 148
 149 ### Configuration
 150
 151 `xds-server` configuration is driven by a JSON config file (`config.json`).
 152
 153 Here is the logic to determine which `config.json` file will be used:
 154 1. from command line option: `--config myConfig.json`
 155 2. `$HOME/.xds/config.json` file
 156 3. `<current dir>/config.json` file
 157 4. `<xds-server executable dir>/config.json` file
 158
 159 Supported fields in configuration file are (all fields are optional and listed values are the default values):
 160 ```
 161 {
 162     "webAppDir": "webapp/dist",                     # location of client dashboard (default: webapp/dist)
 163     "shareRootDir": "${HOME}/.xds/projects",        # root directory where projects will be copied
 164     "logsDir": "/tmp/logs",                         # directory to store logs (eg. syncthing output)
 165     "sdkRootDir": "/xdt/sdk",                       # root directory where cross SDKs are installed
 166     "syncthing": {
 167         "binDir": "./bin",                          # syncthing binaries directory (default: executable directory)
 168         "home": "${HOME}/.xds/syncthing-config",    # syncthing home directory (usually .../syncthing-config)
 169         "gui-address": "http://localhost:8384",     # syncthing gui url (default http://localhost:8384)
 170         "gui-apikey": "123456789",                  # syncthing api-key to use (default auto-generated)
 171     }
 172 }
 173 ```
 174
 175 >**NOTE:** environment variables are supported by using `${MY_VAR}` syntax.
 176
 177 ## Start-up
 178
 179 Use `xds-server-start.sh` script to start all requested tools
 180 ```bash
 181 /usr/local/bin/xds-server-start.sh
 182 ```
 183
 184 >**NOTE** you can define some environment variables to setup for example
 185 logging level `LOGLEVEL` or change logs directory `LOGDIR`.
 186 See head section of `xds-server-start.sh` file to see all configurable variables.
 187
 188
 189 ### Create XDS AGL docker worker container
 190
 191 `xds-server` has been integrated as a flavour of AGL SDK docker image. So to rebuild
 192 docker image just execute following commands:
 193 ```bash
 194 git clone https://git.automotivelinux.org/AGL/docker-worker-generator
 195 cd docker-worker-generator
 196 make build FLAVOUR=xds
 197 ```
 198
 199 You should get `docker.automotivelinux.org/agl/worker-xds:X.Y` image
 200
 201 ```bash
 202 docker images
 203 REPOSITORY                                      TAG                 IMAGE ID            CREATED             SIZE
 204 docker.automotivelinux.org/agl/worker-xds       3.2                 786d65b2792c        6 days ago          602MB
 205 ```
 206
 207 ## Debugging
 208
 209 ### XDS server architecture
 210
 211 The server part is written in *Go* and web app / dashboard (client part) in
 212 *Angular2*.
 213
 214 ```
 215 |
 216 +-- bin/                where xds-server binary file will be built
 217 |
 218 +-- config.json.in      example of config.json file
 219 |
 220 +-- glide.yaml          Go package dependency file
 221 |
 222 +-- lib/                sources of server part (Go)
 223 |
 224 +-- main.go             main entry point of of Web server (Go)
 225 |
 226 +-- Makefile            makefile including
 227 |
 228 +-- README.md           this readme
 229 |
 230 +-- scripts/            hold various scripts used for installation or startup
 231 |
 232 +-- tools/              temporary directory to hold development tools (like glide)
 233 |
 234 +-- vendor/             temporary directory to hold Go dependencies packages
 235 |
 236 +-- webapp/             source client dashboard (Angular2 app)
 237 ```
 238
 239 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
 240
 241
 242 ## TODO:
 243
 244 - replace makefile by build.go to make Windows build support easier
 245 - add more tests
 246 - add more documentation
 247 - add authentication / login (oauth) + HTTPS
 248 - enable syncthing user/password + HTTPS