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