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](https://github.com/iotbzh/xds-exec),
  24 wrappers on `exec` commands that allows you to send commands to `xds-server`
  25 and for example build your application from command-line or from your favorite
  26 IDE (such as 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 # Get script
  49 wget https://raw.githubusercontent.com/iotbzh/xds-server/master/scripts/xds-docker-create-container.sh
  50 # [snip...]
  51
  52 # Create new XDS worker container
  53 bash ./xds-docker-create-container.sh 0 docker.automotivelinux.org/agl/worker-xds:3.99.1
  54 # [snip...]
  55
  56 # Check that new container is running
  57 docker ps
  58
  59 CONTAINER ID        IMAGE                                               COMMAND                  CREATED              STATUS              PORTS                                                                                         NAMES
  60 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
  61 ```
  62
  63 This container exposes following ports:
  64   - 8000 : `xds-server` to serve XDS Dashboard
  65   - 69   : TFTP
  66   - 2222 : ssh
  67
  68 `xds-server` is automatically started as a service on container startup.
  69 If needed you can stop / start it manually using following commands:
  70 ```bash
  71 # Log into docker container
  72 ssh -p 2222 devel@localhost
  73
  74 # Stop XDS server
  75 [15:59:58] devel@agl-worker-seb-laptop-0-seb:~$ /usr/local/bin/xds-server-stop.sh
  76
  77 # Start XDS server
  78 [15:59:58] devel@agl-worker-seb-laptop-0-seb:~$ /usr/local/bin/xds-server-start.sh
  79 ```
  80
  81 On `xds-server` startup, you should get the following output:
  82 ```
  83 ### Configuration in config.json:
  84 {
  85     "webAppDir": "/usr/local/bin/www-xds-server",
  86     "shareRootDir": "/home/devel/.xds/share",
  87     "logsDir": "/tmp/xds-server/logs",
  88     "sdkRootDir": "/xdt/sdk",
  89     "syncthing": {
  90         "binDir": "/usr/local/bin",
  91         "home": "/home/devel/.xds/syncthing-config",
  92         "gui-address": "http://localhost:8384",
  93         "gui-apikey": "1234abcezam"
  94     }
  95 }
  96
  97 ### Start XDS server
  98 nohup /usr/local/bin/xds-server --config /home/devel/.xds/config.json -log warn > /tmp/xds-server/logs/xds-server.log 2>&1
  99 pid=22379
 100 ```
 101
 102 >**NOTE:** You can set LOGLEVEL env variable to increase log level if you need it.
 103 > For example, to set log level to "debug" mode : ` LOGLEVEL=debug /usr/local/bin/xds-server-start.sh`
 104
 105 ### Install SDK cross-toolchain
 106
 107 `xds-server` uses cross-toolchain install into directory pointed by `sdkRootDir` setting (see configuration section below for more details).
 108 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.
 109
 110 Use provided `install-agl-sdks` script, for example to install SDK for ARM64 and Intel corei7-64:
 111
 112 ```bash
 113 # Install ARM64 SDK (automatic download)
 114 /usr/local/bin/xds-utils/install-agl-sdks.sh --aarch aarch64
 115
 116 # Install Intel corei7-64 SDK (using an SDK tarball that has been built or downloaded manually)
 117 /usr/local/bin/xds-utils/install-agl-sdks.sh --aarch corei7-64 --file /tmp/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-corei7-64-toolchain-
 118 3.99.1+snapshot.sh
 119
 120 ```
 121
 122 ### XDS Dashboard
 123
 124 `xds-server` serves a web-application (default port 8000:
 125 [http://localhost:8000](http://localhost:8000) ). So you can now connect your browser to this url and use what we call the **XDS dashboard**.
 126
 127 Then follow instructions provided by this dashboard, knowing that the first time
 128 you need to download and start `xds-agent` on your local machine. To download
 129 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).
 130
 131 See also `xds-agent` [README file](https://github.com/iotbzh/xds-agent) for more
 132 details.
 133
 134
 135 ## Build xds-server from scratch
 136
 137 ### Dependencies
 138
 139 - Install and setup [Go](https://golang.org/doc/install) version 1.7 or
 140 higher to compile this tool.
 141 - Install [npm](https://www.npmjs.com/) : `sudo apt install npm`
 142 - Install [gulp](http://gulpjs.com/) : `sudo npm install -g gulp-cli`
 143
 144 ### Building
 145
 146 Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile:
 147 ```bash
 148  mkdir -p $GOPATH/src/github.com/iotbzh
 149  cd $GOPATH/src/github.com/iotbzh
 150  git clone https://github.com/iotbzh/xds-server.git
 151  cd xds-server
 152  make all
 153 ```
 154
 155 And to install `xds-server` (by default in `/usr/local/bin`):
 156 ```bash
 157 make install
 158 ```
 159
 160 >**NOTE:** Used `DESTDIR` to specify another install directory
 161 >```bash
 162 >make install DESTDIR=$HOME/opt/xds-server
 163 >```
 164
 165 ### Configuration
 166
 167 `xds-server` configuration is driven by a JSON config file (`config.json`).
 168
 169 Here is the logic to determine which `config.json` file will be used:
 170 1. from command line option: `--config myConfig.json`
 171 2. `$HOME/.xds/config.json` file
 172 3. `<current dir>/config.json` file
 173 4. `<xds-server executable dir>/config.json` file
 174
 175 Supported fields in configuration file are (all fields are optional and listed values are the default values):
 176 ```
 177 {
 178     "webAppDir": "webapp/dist",                     # location of client dashboard (default: webapp/dist)
 179     "shareRootDir": "${HOME}/.xds/projects",        # root directory where projects will be copied
 180     "logsDir": "/tmp/logs",                         # directory to store logs (eg. syncthing output)
 181     "sdkRootDir": "/xdt/sdk",                       # root directory where cross SDKs are installed
 182     "syncthing": {
 183         "binDir": "./bin",                          # syncthing binaries directory (default: executable directory)
 184         "home": "${HOME}/.xds/syncthing-config",    # syncthing home directory (usually .../syncthing-config)
 185         "gui-address": "http://localhost:8384",     # syncthing gui url (default http://localhost:8384)
 186         "gui-apikey": "123456789",                  # syncthing api-key to use (default auto-generated)
 187     }
 188 }
 189 ```
 190
 191 >**NOTE:** environment variables are supported by using `${MY_VAR}` syntax.
 192
 193 ## Start-up
 194
 195 Use `xds-server-start.sh` script to start all requested tools
 196 ```bash
 197 /usr/local/bin/xds-server-start.sh
 198 ```
 199
 200 >**NOTE** you can define some environment variables to setup for example
 201 logging level `LOGLEVEL` or change logs directory `LOGDIR`.
 202 See head section of `xds-server-start.sh` file to see all configurable variables.
 203
 204
 205 ### Create XDS AGL docker worker container
 206
 207 `xds-server` has been integrated as a flavour of AGL SDK docker image. So to rebuild
 208 docker image just execute following commands:
 209 ```bash
 210 # Clone docker-worker-generator git repo
 211 git clone https://git.automotivelinux.org/AGL/docker-worker-generator
 212 # Start build that will create a docker image
 213 cd docker-worker-generator
 214 make build FLAVOUR=xds
 215 ```
 216
 217 You should get `docker.automotivelinux.org/agl/worker-xds:X.Y` image
 218
 219 ```bash
 220 # List image that we just built
 221 docker images
 222
 223 REPOSITORY                                      TAG                 IMAGE ID            CREATED             SIZE
 224 docker.automotivelinux.org/agl/worker-xds       3.2                 786d65b2792c        6 days ago          602MB
 225 ```
 226
 227 ## Debugging
 228
 229 ### XDS server architecture
 230
 231 The server part is written in *Go* and web app / dashboard (client part) in
 232 *Angular2*.
 233
 234 ```
 235 |
 236 +-- bin/                where xds-server binary file will be built
 237 |
 238 +-- config.json.in      example of config.json file
 239 |
 240 +-- glide.yaml          Go package dependency file
 241 |
 242 +-- lib/                sources of server part (Go)
 243 |
 244 +-- main.go             main entry point of of Web server (Go)
 245 |
 246 +-- Makefile            makefile including
 247 |
 248 +-- README.md           this readme
 249 |
 250 +-- scripts/            hold various scripts used for installation or startup
 251 |
 252 +-- tools/              temporary directory to hold development tools (like glide)
 253 |
 254 +-- vendor/             temporary directory to hold Go dependencies packages
 255 |
 256 +-- webapp/             source client dashboard (Angular2 app)
 257 ```
 258
 259 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
 260
 261
 262 ## TODO:
 263
 264 - replace makefile by build.go to make Windows build support easier
 265 - add more tests
 266 - add more documentation
 267 - add authentication / login (oauth) + HTTPS
 268 - enable syncthing user/password + HTTPS