# How to run

`xds-server` has been designed to easily compile and debug
[AGL](https://www.automotivelinux.org/) applications. That's why `xds-server` has
been integrated into AGL SDK docker container.

>**Note:** For more info about AGL SDK docker container, please refer to
[AGL SDK Quick Setup](../../../../../getting_started/reference/getting-started/docker-container-setup.html)

## Start xds-server

There are several way to install xds-server and start-up depend of installation type:

| Installation type | Supported<br> host OS   | Start-up                                          | Install instructions |
|-------------------|-------------------------|---------------------------------------------------|----------------------|
| Docker container  | Linux or MacOS          | Automatic based on systemd user service           | [see Installation based on Docker container](../../part-1/server-part.html#docker-container) |
| Virtual Machine   | Linux, MacOS or Windows | Automatic based on systemd user service           | [see Installation based on VirtualBox appliance](../../part-1/server-part.html#virtualbox-appliance) |
| Native            | Linux                   | Automatic based on systemd user service or manual | [see Native installation](../../part-1/server-part.html#native) |
| Native            | MacOS or Windows        | Manually                                          | [see Native installation](../../part-1/server-part.html#native) |

### Automatic start-up based on systemd user service

XDS server is started as a user service by Systemd.

```bash
/usr/lib/systemd/user/xds-server.service
```

Use well-known systemd commands to control `xds-server.service` service.

```bash
# Enter in docker container or VM
# (optional, depending on installation type)
ssh -p 2222 devel@localhost

# Status XDS server:
systemctl --user status xds-server

# Restart XDS server
systemctl --user restart xds-server
```

If needed you can change default setting by defining specific environment
variables file

```bash
ssh -t -p 2222 devel@localhost vim /etc/default/xds-server
```

For example to control log level, just set LOG_LEVEL env variable.

knowing that supported *level* are:

- panic
- fatal
- error
- warn
- info
- debug

```bash
docker exec ${CONTAINER_NAME} bash -c "echo 'LOG_LEVEL=debug' >> /etc/default/xds-server"
ssh -p 2222 devel@localhost -- "systemctl --user restart xds-server"
```

### Manual start-up

On **Linux or MacOS**, simply execute `xds-server` executable:

```bash
/opt/AGL/bin/xds-server
```

On **Windows**, simply execute `xds-server` executable:

```batch
C:\AGL\bin\xds-server.exe
```

<!-- section-note -->
**Note:**

Invoke `xds-server --help` to get more details about possible options that allow
for example to change logging level or select another configuration file.

<!-- end-section-note -->

## XDS server REST API and Web application

`xds-server` exposes a REST API and serves a basic web-application.

REST API based url is `http://localhost:8000/api/v1/` when XDS server is
running on your host (localhost) and basic web-application is available at
`http://localhost:8000`.

Just replace `localhost` by the host name or ip when `xds-server` is running
on another host.

```bash
# Get version using REST API
curl http://localhost:8000/api/v1/version

# Open browser and local xds-server web-application
xdg-open http://localhost:8000
```

Then follow instructions provided on this page to install and start `xds-agent`
that must run locally on your machine.

See also [xds-agent documentation](../2_xds-agent/0_abstract.html) for more details.

## SDK cross-toolchain Management

### Setup to add support of a new SDK family

<!-- section-note -->
**Optional step**: read this chapter only if you plan to add a new SDK family.
<!-- end-section-note -->

`xds-server` dynamically detects supported SDKs by scanning sub-directories of
`sdkScriptsDir` directory (see [Configuration chapter](2_config.html)).

Each sub-directory (usually name is the same as the SDK family) of `sdkScriptsDir`
must contain a set of scripts that will be called by `xds-server` to managed SDKs
of a specific family.

These scripts are:

- `add`: used to add/install a new SDK
- `db-dump`: returned the list of available and installed SDKs (JSON format)
- `db-update`: update SDKs database
- `get-family-config`: returned SDK family configuration structure (JSON format)
- `get-sdk-info`: extract SDK info (JSON format) from a SDK file/tarball
- `remove`: used to remove an existing SDK

For example, here 2 SDKs family (`agl` and `zephyr`) are defined:

```bash
# > tree ./sdks/
./sdks/
├── agl
│   ├── add
│   ├── db-dump
│   ├── db-update
│   ├── get-family-config
│   ├── get-sdk-info
│   └── remove
├── README.md
└── zephyr
    ├── add
│   ├── db-dump
│   ├── db-update
│   ├── get-family-config
│   ├── get-sdk-info
    └── remove
```

On startup `xds-server` will call in order:

- `sdks/*/get-family-config` to get configuration of each SDK family.
- `sdks/*/db-update` to update database (only when `SdkDbUpdate` is set to ̀`startup`,
   see [Configuration chapter](2_config.html) for more details)
- `sdks/*/db-dump` scripts to get the initial list of available and installed SDKs.

Please refer to `sdks/README.md` for more information about scripts definition
and to understand how to add support of a new SDK family.

### Install a new SDK

Please refer to [Installing AGL SDKs](../../part-1/install-sdk.html) chapter.

### Un-install a SDK from command line

Used `sdks` command of `xds-cli` tool to managed SDKs.

```bash
# List installed SDKs
xds-cli sdks ls
List of installed SDKs:
  ID            NAME                                                            STATUS          VERSION         ARCH
  c39e5998      poky-agl_aarch64_4.0.1                                          Installed       4.0.1           aarch64
  d610bfbf      poky-agl-aarch64.current_on_iotbzh_download-3.99.1+snapshot     Installed       3.99.1+snapshot aarch64.current_on_iotbzh_download
  a0ae663d      poky-agl-corei7-64-3.99.1+snapshot                              Installed       3.99.1+snapshot corei7-64
  87f0400b      AGL-release-dab-3.99.3-m3ulcb-nogfx                             Installed       3.99.3          aarch64
  352c0584      poky-agl-corei7-64-3.99.2+snapshot                              Installed       3.99.2+snapshot corei7-64
  d65fe750      AGL-release-eel-latest-qemux86-64                               Installed       4.99.5          corei7-64

# Un-install a SDK
xds-cli sdks uninstall d65fe750
SDK ID d65fe750-d3a7-38f5-83d8-3d3806054f8d successfully deleted.
```

### Un-install a SDK from XDS Dashboard

Open XDS-Dashboard in web-browser and select `SDKs` entry in left side menu.

If needed, switch to `BASIC SDKS VIEW` view and click on trash icon located
in the top-right corner of SDK card.