Document usage of --file option with Intel SDK example
[src/xds/xds-server.git] / 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 # 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 git clone https://git.automotivelinux.org/AGL/docker-worker-generator
211 cd docker-worker-generator
212 make build FLAVOUR=xds
213 ```
214
215 You should get `docker.automotivelinux.org/agl/worker-xds:X.Y` image
216
217 ```bash
218 docker images
219 REPOSITORY                                      TAG                 IMAGE ID            CREATED             SIZE
220 docker.automotivelinux.org/agl/worker-xds       3.2                 786d65b2792c        6 days ago          602MB
221 ```
222
223 ## Debugging
224
225 ### XDS server architecture
226
227 The server part is written in *Go* and web app / dashboard (client part) in
228 *Angular2*.
229
230 ```
231 |
232 +-- bin/                where xds-server binary file will be built
233 |
234 +-- config.json.in      example of config.json file
235 |
236 +-- glide.yaml          Go package dependency file
237 |
238 +-- lib/                sources of server part (Go)
239 |
240 +-- main.go             main entry point of of Web server (Go)
241 |
242 +-- Makefile            makefile including
243 |
244 +-- README.md           this readme
245 |
246 +-- scripts/            hold various scripts used for installation or startup
247 |
248 +-- tools/              temporary directory to hold development tools (like glide)
249 |
250 +-- vendor/             temporary directory to hold Go dependencies packages
251 |
252 +-- webapp/             source client dashboard (Angular2 app)
253 ```
254
255 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
256
257
258 ## TODO:
259
260 - replace makefile by build.go to make Windows build support easier
261 - add more tests
262 - add more documentation
263 - add authentication / login (oauth) + HTTPS
264 - enable syncthing user/password + HTTPS