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
  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 #### Manually setup docker user id
  80
  81 If you plan to **use path-mapping sharing type for your projects**, you need to have the same user id and group id inside and outside docker. By default user and group name inside docker is set `devel` (id `1664`), use following commands to replace id `1664` with your user/group id:
  82 ```bash
  83 # Set docker container name to use (usually agl-xds-xxx where xxx is USERNAME@MACHINENAME-IDX-NAME)
  84 seb@laptop ~$ export CONTAINER_NAME=agl-xds-seb@laptop-0-seb
  85
  86 # First stop xds-server
  87 seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c ""
  88
  89 # Change user and group id inside docker to match your ids
  90 seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "usermod -u $(id -u) devel"
  91 seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "groupmod -g $(id -g) devel"
  92
  93 # Update some files ownership
  94 seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "chown -R devel:devel /home/devel /tmp/xds"
  95 ```
  96
  97
  98 **`xds-server` is automatically started** as a service on container startup.
  99
 100 If the container is running on your localhost, you can access the web interface (what we call the "Dashboard"):
 101
 102 ```bash
 103 seb@laptop ~$ xdg-open http://localhost:8000
 104 ```
 105
 106 If needed you can status / stop / start  it manually using following commands:
 107
 108 ```bash
 109 # Log into docker container
 110 seb@laptop ~$ ssh -p 2222 devel@localhost
 111
 112 # Status XDS server:
 113 devel@docker ~$ sudo systemctl status xds-server.service
 114
 115 # Stop XDS server
 116 devel@docker ~$ sudo systemctl stop xds-server.service
 117
 118 # Start XDS server
 119 devel@docker ~$ sudo systemctl start xds-server.service
 120
 121 # Get XDS server logs
 122 devel@docker ~$ sudo journalctl --unit=xds-server.service --output=cat
 123 ```
 124
 125 ### Manually Start XDS server
 126
 127 XDS server is started as a service by Systemd.
 128
 129 ```bash
 130 /lib/systemd/system/xds-server.service
 131 ```
 132
 133 This Systemd service starts a bash script `/usr/local/bin/xds-server-start.sh`
 134
 135 If you needed you can change default setting by defining specific environment
 136 variables in `/etc/default/xds-server`.
 137 For example to control log level, just set LOGLEVEL env variable knowing that
 138 supported *level* are: panic, fatal, error, warn, info, debug.
 139
 140 ```bash
 141 seb@laptop ~$ ssh -p 2222 devel@localhost
 142 devel@docker ~$ echo 'LOGLEVEL=debug' | sudo tee --append /etc/default/xds-server > /dev/null
 143 devel@docker ~$ sudo systemctl restart xds-server.service
 144 devel@docker ~$ tail -f /tmp/xds-server/logs/xds-server.log
 145 ```
 146
 147 ### Install SDK cross-toolchain
 148
 149 `xds-server` uses cross-toolchain install into directory pointed by `sdkRootDir`
 150 setting (see configuration section below for more details).
 151 For now, you need to install manually SDK cross toolchain. There are not embedded
 152 into docker image by default because the size of these tarballs is too big.
 153
 154 Use provided `install-agl-sdks` script, for example to install SDK for ARM64 and
 155 Intel corei7-64:
 156
 157 ```bash
 158 seb@laptop ~$ ssh -p 2222 devel@localhost
 159
 160 # Install ARM64 SDK (automatic download)
 161 devel@docker ~$ sudo /usr/local/bin/xds-utils/install-agl-sdks.sh --arch aarch64
 162
 163 # Install Intel corei7-64 SDK (using an SDK tarball that has been built or downloaded manually)
 164 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-
 165 3.99.1+snapshot.sh
 166
 167 ```
 168
 169 ### XDS Dashboard
 170
 171 `xds-server` serves a web-application at [http://localhost:8000](http://localhost:8000)
 172 when XDS server is running on your host. Just replace `localhost` by the host
 173 name or ip when XDS server is running on another host. So you can now connect
 174 your browser to this url and use what we call the **XDS dashboard**.
 175
 176 ```bash
 177 xdg-open http://localhost:8000
 178 ```
 179
 180 Then follow instructions provided by this dashboard, knowing that the first time
 181 you need to download and start `xds-agent` on your local machine.
 182
 183 To download this tool, just click on download icon in dashboard configuration
 184 page or download one of `xds-agent` released tarball: [https://github.com/iotbzh/xds-agent/releases](https://github.com/iotbzh/xds-agent/releases).
 185
 186 See also `xds-agent` [README file](https://github.com/iotbzh/xds-agent) for more details.
 187
 188 ## Build xds-server from scratch
 189
 190 ### Dependencies
 191
 192 - Install and setup [Go](https://golang.org/doc/install) version 1.7 or
 193 higher to compile this tool.
 194 - Install [npm](https://www.npmjs.com/)
 195 - Install [gulp](http://gulpjs.com/)
 196
 197 Ubuntu:
 198
 199 ```bash
 200  sudo apt-get install golang npm curl git zip
 201  sudo npm install -g gulp-cli
 202 ```
 203
 204 openSUSE:
 205
 206 ```bash
 207  sudo zypper install go npm git curl zip
 208  sudo npm install -g gulp-cli
 209 ```
 210
 211 Don't forget to open new user session after installing the packages.
 212
 213 ### Building
 214
 215 #### Native build
 216
 217 Create a GOPATH variable(must be a full path):
 218
 219 ```bash
 220  export GOPATH=$(realpath ~/workspace_go)
 221 ```
 222
 223 Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile:
 224
 225 ```bash
 226  mkdir -p $GOPATH/src/github.com/iotbzh
 227  cd $GOPATH/src/github.com/iotbzh
 228  git clone https://github.com/iotbzh/xds-server.git
 229  cd xds-server
 230  make all
 231 ```
 232
 233 And to install `xds-server` (by default in `/usr/local/bin`):
 234
 235 ```bash
 236  make install
 237 ```
 238
 239 >**NOTE:** Used `DESTDIR` to specify another install directory
 240 >```bash
 241 >make install DESTDIR=$HOME/opt/xds-server
 242 >```
 243
 244 #### XDS docker image
 245
 246 As an alternative to a pre-build image, you can rebuild the container from scratch.
 247 `xds-server` has been integrated as a flavour of AGL SDK docker image.
 248 So to rebuild docker image just execute following commands:
 249
 250 ```bash
 251 # Clone docker-worker-generator git repo
 252 git clone https://git.automotivelinux.org/AGL/docker-worker-generator
 253 # Start build that will create a docker image
 254 cd docker-worker-generator
 255 make build FLAVOUR=xds
 256 ```
 257
 258 ### Configuration
 259
 260 `xds-server` configuration is driven by a JSON config file (`config.json`).
 261
 262 Here is the logic to determine which `config.json` file will be used:
 263
 264 1. from command line option: `--config myConfig.json`
 265 1. `$HOME/.xds/config.json` file
 266 1. `<current dir>/config.json` file
 267 1. `<xds-server executable dir>/config.json` file
 268
 269 Supported fields in configuration file are (all fields are optional and example
 270 below corresponds to the default values):
 271
 272 - **httpPort** : HTTP port of client webapp / dashboard
 273 - **webAppDir** : location of client dashboard (default: webapp/dist)
 274 - **shareRootDir** : root directory where projects will be copied
 275 - **logsDir**  : directory to store logs (eg. syncthing output)
 276 - **sdkRootDir** : root directory where cross SDKs are installed
 277 - **syncthing.binDir** : syncthing binaries directory (default: executable directory)
 278 - **syncthing.home"** : syncthing home directory (usually .../syncthing-config)
 279 - **syncthing.gui-address** : syncthing gui url (default http://localhost:8384)
 280 - **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated)
 281
 282 ```json
 283 {
 284     "httpPort": 8000,
 285     "webAppDir": "webapp/dist",
 286     "shareRootDir": "${HOME}/.xds/projects",
 287     "logsDir": "/tmp/logs",
 288     "sdkRootDir": "/xdt/sdk",
 289     "syncthing": {
 290         "binDir": "./bin",
 291         "home": "${HOME}/.xds/syncthing-config",
 292         "gui-address": "http://localhost:8384",
 293         "gui-apikey": "123456789",
 294     }
 295 }
 296 ```
 297
 298 >**NOTE:** environment variables are supported by using `${MY_VAR}` syntax.
 299
 300 ## Debugging
 301
 302 ### XDS server architecture
 303
 304 The server part is written in *Go* and web app / dashboard (client part) in
 305 *Angular2*.
 306
 307 ```
 308 |
 309 +-- bin/                where xds-server binary file will be built
 310 |
 311 +-- agent-config.json.in      example of config.json file
 312 |
 313 +-- glide.yaml          Go package dependency file
 314 |
 315 +-- lib/                sources of server part (Go)
 316 |
 317 +-- main.go             main entry point of of Web server (Go)
 318 |
 319 +-- Makefile            makefile including
 320 |
 321 +-- README.md           this readme
 322 |
 323 +-- scripts/            hold various scripts used for installation or startup
 324 |
 325 +-- tools/              temporary directory to hold development tools (like glide)
 326 |
 327 +-- vendor/             temporary directory to hold Go dependencies packages
 328 |
 329 +-- webapp/             source client dashboard (Angular2 app)
 330 ```
 331
 332 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
 333
 334 ## TODO
 335
 336 - replace makefile by build.go to make Windows build support easier
 337 - add more tests
 338 - add more documentation
 339 - add authentication / login (oauth) + HTTPS
 340 - enable syncthing user/password + HTTPS