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
  41 ```bash
  42 seb@laptop ~$ wget -O - http://iot.bzh/download/public/2017/XDS/docker/docker_agl_worker-xds-latest.tar.xz | docker load
  43 ```
  44
  45 ### List container
  46
  47 You should get `docker.automotivelinux.org/agl/worker-xds:X.Y` image
  48
  49 ```bash
  50 # List image that we just built
  51 seb@laptop ~$ docker images | grep worker-xds
  52
  53 docker.automotivelinux.org/agl/worker-xds       3.99.1              786d65b2792c        6 days ago          602MB
  54 ```
  55
  56 ### Start xds-server within the container
  57
  58 Use provided script to create a new docker image and start a new container:
  59
  60 ```bash
  61 # Get script
  62 seb@laptop ~$ wget https://raw.githubusercontent.com/iotbzh/xds-server/master/scripts/xds-docker-create-container.sh
  63
  64 # Create new XDS worker container
  65 seb@laptop ~$ bash ./xds-docker-create-container.sh docker.automotivelinux.org/agl/worker-xds:X.Y
  66
  67 # Check that new container is running
  68 seb@laptop ~$ docker ps | grep worker-xds
  69
  70 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-xds-seb@laptop-0-seb
  71 ```
  72
  73 This container (ID=0) exposes following ports:
  74
  75 - 8000 : `xds-server` to serve XDS Dashboard
  76 - 69   : TFTP
  77 - 2222 : ssh
  78
  79 **`xds-server` is automatically started** as a service on container startup.
  80
  81 If the container is running on your localhost, you can access the web interface (what we call the "Dashboard"):
  82
  83 ```bash
  84 seb@laptop ~$ xdg-open http://localhost:8000
  85 ```
  86
  87 If needed you can status / stop / start  it manually using following commands:
  88
  89 ```bash
  90 # Log into docker container
  91 seb@laptop ~$ ssh -p 2222 devel@localhost
  92
  93 # Status XDS server:
  94 devel@docker ~$ sudo systemctl status xds-server.service
  95
  96 # Stop XDS server
  97 devel@docker ~$ sudo systemctl stop xds-server.service
  98
  99 # Start XDS server
 100 devel@docker ~$ sudo systemctl start xds-server.service
 101
 102 # Get XDS server logs
 103 devel@docker ~$ sudo journalctl --unit=xds-server.service --output=cat
 104 ```
 105
 106 ### Manually Start XDS server
 107
 108 XDS server is started as a service by Systemd.
 109
 110 ```bash
 111 /lib/systemd/system/xds-server.service
 112 ```
 113
 114 This Systemd service starts a bash script `/usr/local/bin/xds-server-start.sh`
 115
 116 If you needed you can change default setting by defining specific environment
 117 variables in `/etc/default/xds-server`.
 118 For example to control log level, just set LOGLEVEL env variable knowing that
 119 supported *level* are: panic, fatal, error, warn, info, debug.
 120
 121 ```bash
 122 seb@laptop ~$ ssh -p 2222 devel@localhost
 123 devel@docker ~$ echo 'LOGLEVEL=debug' | sudo tee --append /etc/default/xds-server > /dev/null
 124 devel@docker ~$ sudo systemctl restart xds-server.service
 125 devel@docker ~$ tail -f /tmp/xds-server/logs/xds-server.log
 126 ```
 127
 128 ### Install SDK cross-toolchain
 129
 130 `xds-server` uses cross-toolchain install into directory pointed by `sdkRootDir`
 131 setting (see configuration section below for more details).
 132 For now, you need to install manually SDK cross toolchain. There are not embedded
 133 into docker image by default because the size of these tarballs is too big.
 134
 135 Use provided `install-agl-sdks` script, for example to install SDK for ARM64 and
 136 Intel corei7-64:
 137
 138 ```bash
 139 seb@laptop ~$ ssh -p 2222 devel@localhost
 140
 141 # Install ARM64 SDK (automatic download)
 142 devel@docker ~$ sudo /usr/local/bin/xds-utils/install-agl-sdks.sh --arch aarch64
 143
 144 # Install Intel corei7-64 SDK (using an SDK tarball that has been built or downloaded manually)
 145 devel@docker ~$ sudo /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-
 146 3.99.1+snapshot.sh
 147
 148 ```
 149
 150 ### XDS Dashboard
 151
 152 `xds-server` serves a web-application at [http://localhost:8000](http://localhost:8000)
 153 when XDS server is running on your host. Just replace `localhost` by the host
 154 name or ip when XDS server is running on another host. So you can now connect
 155 your browser to this url and use what we call the **XDS dashboard**.
 156
 157 ```bash
 158 xdg-open http://localhost:8000
 159 ```
 160
 161 Then follow instructions provided by this dashboard, knowing that the first time
 162 you need to download and start `xds-agent` on your local machine.
 163
 164 To download this tool, just click on download icon in dashboard configuration
 165 page or download one of `xds-agent` released tarball: [https://github.com/iotbzh/xds-agent/releases](https://github.com/iotbzh/xds-agent/releases).
 166
 167 See also `xds-agent` [README file](https://github.com/iotbzh/xds-agent) for more details.
 168
 169 ## Build xds-server from scratch
 170
 171 ### Dependencies
 172
 173 - Install and setup [Go](https://golang.org/doc/install) version 1.7 or
 174 higher to compile this tool.
 175 - Install [npm](https://www.npmjs.com/)
 176 - Install [gulp](http://gulpjs.com/)
 177
 178 Ubuntu:
 179
 180 ```bash
 181  sudo apt-get install golang npm curl git zip
 182  sudo npm install -g gulp-cli
 183 ```
 184
 185 openSUSE:
 186
 187 ```bash
 188  sudo zypper install go npm git curl zip
 189  sudo npm install -g gulp-cli
 190 ```
 191
 192 Don't forget to open new user session after installing the packages.
 193
 194 ### Building
 195
 196 #### Native build
 197
 198 Create a GOPATH variable(must be a full path):
 199
 200 ```bash
 201  export GOPATH=$(realpath ~/workspace_go)
 202 ```
 203
 204 Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile:
 205
 206 ```bash
 207  mkdir -p $GOPATH/src/github.com/iotbzh
 208  cd $GOPATH/src/github.com/iotbzh
 209  git clone https://github.com/iotbzh/xds-server.git
 210  cd xds-server
 211  make all
 212 ```
 213
 214 And to install `xds-server` (by default in `/usr/local/bin`):
 215
 216 ```bash
 217  make install
 218 ```
 219
 220 >**NOTE:** Used `DESTDIR` to specify another install directory
 221 >```bash
 222 >make install DESTDIR=$HOME/opt/xds-server
 223 >```
 224
 225 #### XDS docker image
 226
 227 As an alternative to a pre-build image, you can rebuild the container from scratch.
 228 `xds-server` has been integrated as a flavour of AGL SDK docker image.
 229 So to rebuild docker image just execute following commands:
 230
 231 ```bash
 232 # Clone docker-worker-generator git repo
 233 git clone https://git.automotivelinux.org/AGL/docker-worker-generator
 234 # Start build that will create a docker image
 235 cd docker-worker-generator
 236 make build FLAVOUR=xds
 237 ```
 238
 239 ### Configuration
 240
 241 `xds-server` configuration is driven by a JSON config file (`config.json`).
 242
 243 Here is the logic to determine which `config.json` file will be used:
 244
 245 1. from command line option: `--config myConfig.json`
 246 1. `$HOME/.xds/config.json` file
 247 1. `<current dir>/config.json` file
 248 1. `<xds-server executable dir>/config.json` file
 249
 250 Supported fields in configuration file are (all fields are optional and example
 251 below corresponds to the default values):
 252
 253 - **httpPort** : HTTP port of client webapp / dashboard
 254 - **webAppDir** : location of client dashboard (default: webapp/dist)
 255 - **shareRootDir** : root directory where projects will be copied
 256 - **logsDir**  : directory to store logs (eg. syncthing output)
 257 - **sdkRootDir** : root directory where cross SDKs are installed
 258 - **syncthing.binDir** : syncthing binaries directory (default: executable directory)
 259 - **syncthing.home"** : syncthing home directory (usually .../syncthing-config)
 260 - **syncthing.gui-address** : syncthing gui url (default http://localhost:8384)
 261 - **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated)
 262
 263 ```json
 264 {
 265     "httpPort": 8000,
 266     "webAppDir": "webapp/dist",
 267     "shareRootDir": "${HOME}/.xds/projects",
 268     "logsDir": "/tmp/logs",
 269     "sdkRootDir": "/xdt/sdk",
 270     "syncthing": {
 271         "binDir": "./bin",
 272         "home": "${HOME}/.xds/syncthing-config",
 273         "gui-address": "http://localhost:8384",
 274         "gui-apikey": "123456789",
 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 ## TODO
 316
 317 - replace makefile by build.go to make Windows build support easier
 318 - add more tests
 319 - add more documentation
 320 - add authentication / login (oauth) + HTTPS
 321 - enable syncthing user/password + HTTPS