
## vlkb-soda

is a web-application to access astronomical data stored in FITS-files.
It implements [IVOA SODA v1.0](https://ivoa.net/documents/SODA/20170517/index.html) and it supports security by OpenIDConnect/OAuth2.0 and protects connections by TLS.

When used with [vlkb-siav2](https://ict.inaf.it/gitlab/ViaLactea/vlkb-siav2) they provide complete data-discovery and access solution.

## Launching the service

The vlkb-soda service is available as a docker-image and may be launched as examplified in this [**compose.yaml**](docker/example-compose-soda.yaml). Mount the root of the FITS-file store to internal /srv/datasets directory. Also set the service port-number and ACCESS_CONTEXT_ROOT. To see that the instance is running, access the availability endpoint:

```bash
curl --get http://localhost:8004/vlkb/datasets/availability
```


## Enpoints

- **availability** is a [VOSI](https://ivoa.net/documents/VOSI/20170524/REC-VOSI-1.1.html) end-point and returns information whether the service is active
- **capabilities** is a [VOSI](https://ivoa.net/documents/VOSI/20170524/REC-VOSI-1.1.html) end-point which describes service' functions and paramters
- **soda** synchronous end-point provides [SODA](https://ivoa.net/documents/SODA/20170517/index.html) service
- **uws_mcutout** a non-standard asynchronous [UWS](https://ivoa.net/documents/UWS/20161024/REC-UWS-1.1-20161024.html#ApplicationsOfUWS) end-point which allows several cuts to be specified in one request by own [Job Description Language](JDL.md). All cuts are returned compressed in one tar.gz file


## Security

The data store may hold public and/or private collections.

The vlkb-soda supports OIDC/OAuth2.0 protocol and will validate access token in the request.
Non authenticated requests may be allowed by configuration, and will access only public data.

If request passes token validation, group-based authorization check is performed. A user may access the data
if at least on of the user's groups is allowed the access. Access rights for data collections are held in the authorization table.


## Docker image

is available from the gitlab-repository of this project.

SODA-docker's internal mount point for the FITS-files storage is **/srv/datasets** (read-only).

SODA-docker's internal mount point which temporarely holds cut files is **/srv/cutouts** (read-write) for **mcutout only**.


Configuration parameters are set by these docker environment variables:


| parameter | description  |
|---------|--------------|
| **ACCESS_CONTEXT_ROOT** | root of the vlkb-soda end-points |
| **OIDC_INTROSPECT** | URL to OAuth2.0 introspect end-point for token validation |
| **OIDC_RAP_URL** | root URL of an Open ID Connect comaptible identity service |
| **OIDC_GMS_URL** | root URL of Group Management Service |
| **OIDC_CLIENT** | client-id of a Relying party |
| **OIDC_SECRET** | secret of of the client |
| **AUTHZ_DB_URL** | DB where a table with authorization info ('goups' column) can be found |
| **AUTHZ_DB_SCHEMA** | schema of the authorization table |
| **AUTHZ_DB_USERNAME** | user in the DB with authorization table |
| **AUTHZ_DB_PASSWORD** | password for the DB-user |
| **CUTOUTS_URL** | access point to download resulting cuts (**mcutout only**) |

Context-root parameter uses 'tomcat syntax' in which the forward-slash path-separator is replaced with hash: vlkb#datasets -> vlkb/datasets

