Onyxia API

This is the server part of the Onyxia datalab.
It interacts with your container orchestrator to deploy users services.
Onyxia supports both Mesos (using Marathon) and Kubernetes (using Helm).
Deployable services are listed and configured inside catalogs (Universe for Marathon, Helm charts for Helm).
Default catalogs are from InseeFrlab : Universe datascience and Inseefrlab helm charts but more catalogs can be added.

The opensourcing (and documentation) is still a work in progress, please be patient :)

Quick start

Using docker

docker run -p 8080:8080 inseefrlab/onyxia-api

Using Java / maven (from sources)

git clone https://github.com/InseeFrLab/onyxia-api.git
cd onyxia-api
mvn spring-boot:run

Using Helm (work in progress)

A helm package is available at inseefrlab

helm repo add inseefrlab https://inseefrlab.github.io/helm-charts
helm install inseefrlab/onyxia

Note that this installs both the API and the UI

Usage

Once onyxia is started, browse to http://localhost:8080 to get the OpenAPI documentation.
Onyxia-API is primarly made to work with the webapp Onyxia-UI.
If you use it in other ways, we would love to hear from you :)

Configuration

Main configuration file is onyxia-api/src/main/resources/application.properties.
Each variable can be overriden using environment variables.

Authentication configuration

Key	Default	Description
authentication.mode	none	Supported modes are : none, openidconnect (must be configured)

Open id configuration

Key	Default	Description
keycloak.realm		See Keycloak configuration
keycloak.resource		See Keycloak configuration
keycloak.auth-server-url		See Keycloak configuration
keycloak.ssl-required	external	See Keycloak configuration
keycloak.public-client	true	See Keycloak configuration
keycloak.enable-basic-auth	true	See Keycloak configuration
keycloak.bearer-only	true	See Keycloak configuration
keycloak.disable-trust-manager	false	See Keycloak configuration

Regions configuration :

The env variable that configures regions is regions.
A valid JSON is expected with a list of region :

[
  {
    "regionId": "kub",
    "type": "KUBERNETES",
    "namespace-prefix": "user-",
    "publish-domain": "fakedomain.kub.example.com",
    "cloudshell": {
      "catalogId": "inseefrlab-helm-charts",
      "packageName": "cloudshell"
    }
  },
  {
    "regionId": "marathon",
    "type": "MARATHON",
    "serverUrl": "",
    "publish-domain": "fakedomain.marathon.example.com",
    "namespace-prefix": "users",
    "marathon-dns-suffix": "marathon.containerip.dcos.thisdcos.directory",
    "serviceMonitoringURLPattern": "https://graphana.example.com/$appIdSlug",
    "cloudshell": {
      "catalogId": "internal",
      "packageName": "shelly"
    },
    "auth": {
      "token": "xxxxx"
    }
  }
]

when using docker, passing json as env can be done using :

docker run -p 8080:8080 --env "regions=$(<conf.json)" inseefrlab/onyxia-api

Catalogs configuration

Key	Default	Description
catalogs.configuration	classpath:catalogs.json	Catalogs to use. Defaults to catalogs.json. http://, https:// and file: schemes are supported
catalogs.refresh.ms	300000 (5 minutes)	The rate at which the catalogs should be refreshed. <= 0 means no refreshs after initial loading

Other configurations

Key	Default	Description
springdoc.swagger-ui.path	/	Open API (swagger) UI path
springdoc.swagger-ui.oauth.clientId	``	clientid use by swagger to authenticate the user, in general the same which is use by onyxia-ui is ok.

Onyxia Universe package format extension

Onyxia extends the official Universe format (see https://github.com/mesosphere/universe) to enhance it.
This format extension is fully interoperable with the official Universe format meaning Onyxia works with any Universe and Universes using Onyxia's extension should be usable in other apps.

The specification is defined here.

An example of a Universe using this extension is available here.