1 of 29

v9

Admin doc

Install

Convinced by Onyxia? Let's see how you can get your own instance today!

Oneliner

If you are already familiar with Kubernetes and Helm, here's how you can get an Onyxia instance up and running in just a matter of seconds.

helm repo add onyxia https://inseefrlab.github.io/onyxia

cat << EOF > ./onyxia-values.yaml
ingress:
  enabled: true
  hosts:
    - host: onyxia.my-domain.net
EOF

helm install onyxia onyxia/onyxia -f onyxia-values.yaml

# Navigate to https://onyxia.my-domain.net

With this minimal configuration, you'll have an Onyxia instance operating in a degraded mode, which lacks features such as authentication, S3 explorer, secret management, etc. However, you will still retain the capability to launch services from the catalog.

Whether you are a Kubernetes veteran or a beginner with cloud technologies, this guide aims to guide you through the instantiation and configuration of an Onyxia instance with it's full range of features enabled. Let's dive right in! 🤿

First let's make sure we have a suitable deployment environement to work with!

Kubernetes

Provision a Kubernetes cluster

First you'll need a Kubernetes cluster. If you have one already you can skip and directly go to .

maintains great tutorials for Kubernetes clusters on , or .

Pick one of the three and follow the guide.

You can stop after the .

GitOps

Let's install ArgoCD to manage and monitor our Onyxia Datalab deployment!

At this stage of this installation process we assumes that:

You have a Kubernetes cluster and kubectl configured
datalab.my-domain.net and *.lab.my-domain.net's DNS are pointing to your cluster's external address. my-domain.net being a domain that you own.
Your ingress-nginx is set up with a default TLS certificate that covers both datalab.my-domain.net and *.lab.my-domain.net, processing all ingress objects, even those that do not have a class specified.

We can proceed with manually installing various services via Helm to set up the datalab. However, it's more convenient and reproducible to maintain a Git repository that outlines the required services that we need for our datalab, allowing to handle the deployment for us.

To clarify, using ArgoCD is merely an approach that we recommend, but it is by no means a requirement. Feel free to manually helm install the different services using the values.yaml from !

Let's install ArgoCD on the our cluster.

Now you have to get the password that have been automatically generated to protect ArgoCD's admin console. Allow some time for ArgoCD to strart, you can follow the progress by running kubectl get pods and making sure that all pod are ready 1/1. After that running this command will print the password:

You can now login to https://argocd.lab.my-domain.net using:

username: admin
password: <the output of the previous command (without the % at the end)>

Now that we have an ArgoCD we want to connect it to a Git repository that will describe what services we want to be running on our cluster.

Let's fork the onyxia-ops GitHub repo and use it to deploy an Onyxia instance!

Note that in this guide, we use GitHub, but feel free to fork the repository on GitLab or any other forge. You'll need to slightly adapt the instructions, but you should be able to follow along!

At this point you should have a very bare bone Onyxia instance that you can use to launch services.

What's great, is that now, if you want to update the configuration of your Onyxia instance you only have to commit the change to your GitOps repo, ArgoCD will takes charge of restarting the service for you with the new configuration. To put that to the test try to modify your Onyxia configuration by setting up a global alert that will be shown as a banner to all users!

After a few seconds, if you reload https://datalab.my-domain.net you should see the message!

Next step is to see how to enable your user to authenticate themselvs to your datalab!

User authentication

Using Keycloak to enable user authentication

Let's setup Keycloak to enable users to create account and login to our Onyxia.

Note that in this instalation guide we make you use Keycloak but you can use any identity server that is Open ID Connect compliant.

Deploying Keycloak

We're going to install Keycloak just like we installed Onyxia.

Before anything open in your onyxia-ops repo and change the passwords. Also write down the , you'll need it to connect to the Keycloak console.

Try to remember, when you to also update .

Configuring Keycloak

You can now login to the administration console of https://auth.lab.my-domain.net/auth/ and login using username: keycloak and password: <the one you've wrote down earlier>.

Create a realm called "datalab" (or something else), go to Realm settings
1. On the tab General
  1. User Profile Enabled: On

Now you want to ensure that the username chosen by your users complies with Onyxia requirement (only alphanumerical characters) and define a list of email domain allowed to register to your service.

Go to Realm Settings (on the left panel) -> Tab User Profile (this tab shows up only if User Profile is enabled in the General tab and you can enable user profile only if you have started Keycloak with -Dkeycloak.profile=preview) -> JSON Editor.

Now you can edit the file as suggested in the following DIFF snippet. Be mindful that in this example we only allow emails @gmail.com and @hotmail.com to register you want to edit that.

Now our Keycloak server is fully configured we just need to update our Onyxia deployment to let it know about it.

Updating the Onyxia configuration

In your GitOps repo you now want to update your onyxia configuration.

Here is the DIFF of the onyxia configuration:

Now your users should be able to create account, log-in, and start services on their own Kubernetes namespace.

Next step in the installation proccess it to enable all the S3 related features of Onyxia:

Data (S3)

Enable S3 storage via MinIO S3

Onyxia uses AWS Security Token Service API to obtain S3 tokens on behalf of your users. We support any S3 storage compatible with this API. In this context, we are using MinIO, which is compatible with the Amazon S3 storage service and we demonstrate how to integrate it with Keycloak.

Creating the 'minio' Keycloak client

Before configuring MinIO, let's create a new Keycloak client (from the previous existing "datalab" realm).

Deploying MinIO

Before deploying MinIO on the cluster let's set, in the MinIO configuration file, the OIDC client secret we have copied in the previous step.

Once you've done that you can deploy MinIO!

Creating the 'onyxia-minio' Keycloak client

Before configuring the onyxia region to create tokens we should go back to Keycloak and create a new client to enable onyxia-web to request token for MinIO. This client is a little bit more complex than other if you want to manage durations (here 7 days) and this client should have a claim name policy and with a value of stsonly according to our last deployment of MinIO.

Updating the Onyxia configuration

Now let's update our Onyxia configuration to let it know that there is now a S3 server available on the cluster.

Diff of the changes applied to the Onyxia configuration:

Congratulation, all the S3 related features of Onyxia are now enabled in your instance! Now if you navigate to your Onyxia instance you should have My Files in the left menu.

Next step in the installation process is to setup Vault to provide a way to your user so store secret and also to provide something that Onyxia can use as a persistance layer for user configurations.

Vault

Let's use hashicorp Vault for storing the user secrets.

Vault is also used by Onyxia as the persistance layer for all saved configuration. If you don't have a vault all user settings are stored in the local storage.

Onyxia-web use vault as a storage for two kinds of secrets : 1. secrets or information generate by Onyxia to store differents values (ui preferences for example) 2. user secrets Vault must be configured with JWT or OIDC authentification methods.

As vault needs to be initialized with a master key, it can't be directly configured with all parameters such as oidc or access policies and roles. So first step we create a vault with dev mode (do not use this in production and do your initialization with any of the recommanded configuration : shamir, gcp, another vault)

Theme and branding

Customize your Onyxia instance with your assets and your colors, make it your own!

The full documentation of the available parameter can be found here:

Note that your custom assets are imported into your Onyxia instance via the use of the CUSTOM_RESOURCES parameter, url of a ZIP archive that should contain your assets. An example is given at the top of the .env file.

Onyxia is configured to make the the browser cache assets so they are not re-downloaded each time the user access the app.

If you update some of your asset but keep the same URL, you can force the browser of your users to download the new version by adding a query parameter to the URL. Eample:

HEADER_LOGO: "%PUBLIC_URL%/custom-resources/logo.svg?v=2"

Make sure to checkout the version of this document that matches the Onyxia version that you are deploying. .

Default looks

Here are two base look that you can use a starting point of your configuration.

France

👉

Ultraviolet

👉

Setting up group projects

Enabling a group of users to share the same Kubernetes namespace to work on something together.

The user interface of onyxia enables to create projects for groups of Onyxia users.

Users will be able to dynamically switch from one project to another using a select input in the header.

This select doesn't appear when the user isn't in any group project.

All users of a group project share:

The Kubernetes namespace, in "My Services" you can see everything that's running, including services launched by other person of the group.
Project settings. If a user change a project setting, it affects every member of the group.
Secrets
S3 Bucket (or an S3 subpath)

As of today, new group can only be created by Onyxia instance administrator, on demand and the procedure to create group is not publicly documented yet because we're still actively working on it. However, if you want to enable this feature for your users, reach us, we will guide you through it!

Security consideration

Information about security considerations

1. Autolaunch Feature

The autolaunch feature empowers you to create HTTP links that automatically deploy an environment. This is an invaluable tool for initiating trainings effortlessly. However, exercise caution while using it as it could pose a security risk to the user. Consider disabling this feature if it doesn't suit your requirements or if security is a primary concern.

Disable Autolaunch

2. Group Feature

Onyxia is primarily designed to allocate resources such as a namespace and an S3 bucket to an individual user for work purposes. Additionally, it incorporates a feature that allows multiple users to share access to the same resources within a project. While this can be extremely beneficial for collaboration, be aware that it might be exploited by a malicious user within the group to leverage the privileges of another project member. Always monitor shared resources and maintain proper user access control to prevent such security breaches.

Migration guides

v8 -> v9

tl;dr: Breaking change, defaultConfiguration in region configuration is not allowed anymore and has been replaced by JSONSchemas override using the new api.schemas key from v9 helm chart.

Onyxia v9 allows administrators to define custom JSON schemas, allowing them to override the default schemas provided by the chart. Prior to this change, Onyxia relied on providing default values for specific keys in the region configuration : defaultConfiguration.

Chart owners can now define which properties can be overridden using a JSON Schema.

Here is an example of a Chart that supports JSONSchemas (taken from the default IDE catalog, see ) :

The overwriteDefaultWith attribute was the old method for overriding, instructing Onyxia to use the "defaultConfiguration" from the Region. This method is no longer supported in v9, though it can still be used for catalog compatibility with v8.

In v9, overwriteDefaultWith has been replaced by overwriteSchemaWith, which offers more flexibility due to the capabilities of JSON Schemas. Default schemas are bundled with Onyxia-API and will be used if no override is provided. You can find these default schemas here: .

To override a schema, use the new schemas key from the v9 Helm chart and provide the list of schemas you want to override. For more details, refer to the documentation: .

Onyxia v9 will fail to start with error message :

FATAL : Setting defaultConfiguration in region is no longer supported and has been replaced by JSONSchema support. See migration guide at https://docs.onyxia.sh/admin-doc/migration-guides/v8-greater-than-v9

if you don't remove the defaultConfiguration from the region configuration.

v7 -> v8

You can now have comments, trailing comas and single quotes in your region and catalog parameters! See the PR.

In this release, the Onyxia S3 integration has been completely revamped!

This is the DIFF you have to apply to your Onyxia configuration assuming you have a typical MinIO integration configured:

onyxia-values.yaml

 ...
 api:
   ...
   regions:
     [
       {
         ...
         "data": {
           "S3": {
-            "type": "minio",
             "URL": "https://minio.lab.my-domain.net",
             "region": "us-east-1",
-            "bucketClaim": "preferred_username",
-            "defaultDurationSeconds": 86400,
-            "oidcConfiguration": {
-              "clientID": "onyxia-minio"
-            },
+            "sts": {
+              "durationSeconds": 86400,
+              "oidcConfiguration": {
+                "clientID": "onyxia-minio"
+              }
+            },
-            "bucketPrefix": "user-",
-            "groupBucketPrefix": "projet-",
+            "workingDirectory": {
+              "bucketMode": "multi",
+              "bucketNamePrefix": "user-",
+              "bucketNamePrefixGroup": "projet-"
+            }
           },
           ...

v6 -> v7

In this major version a lot of the parameters of the webapp have been updated/refined. Here is the changes you need to apply to your values.json to migrate smoothly.

The `THEME_ID` parameter has been removed.

Onyxia is now fully customizable instead of just letting you pick within a handful of predefined themes.

v5 -> v6

The only breaking change in this release is the split of Onyxia service account into two separate service accounts : one for the API (which usually requires high permission to deploy services) and one for the WEB pod (qui usually should not have any permissions tied to it). Due to this change, the global serviceAccount values key was duplicated in both web.serviceAccount and api.serviceAccount. See:

and

Example of change :

v4 -> v5

The primary breaking change in this release pertains to Keycloak configuration. With this update, you're no longer limited to using Keycloak; any OIDC-compliant identity provider is now supported. To accommodate this new feature, you'll need to make some adjustments to the configuration of your Onyxia instance.

You don't need to specify the issuerURI in multiple locations as we have done here. If you're using just one identity server (You have only one Keycloak server for example), you can set the issuerURI solely in api->env->oidc.issuer-uri.

Migrating to the new helm repo

Previously, the Helm chart of Onyxia was hosted on the inseefrlab/helm-charts repo and has now been moved to inseefrlab/onyxia. As a result you would now install Onyxia like this:

In the following we assume the current version of Onyxia is 4.1.4 but you are encorging to use the latest version instead. .

If you use ArgoCD for deploying onyxia:

You no longer need to manually manage the version of and , now, if you want to update Onyxia, you just update the chart version number.

For the Keycloak theme, the version is now synchronized with the Onyxia version.

Contributors doc

The Web Application

The TypeScript App that runs in the browser.

This is the documentation for .

You have a video here where we guide you through the setup of the dev environnement:

Technical stack

Technologies at play in Onyxia-web

To find your way in Onyxia, the best approach is to start by getting a surface-level understanding of the libraries that are leveraged in the project.

Modules marked by 🐔 are our own.

Architecture

Main rules

contains the React application, it's the UI of the app.

The REST API

The backend REST API in Java

This is the documentation for .

It's the part of the App that runs in the clusters. It handles the things that can't be done directly from the frontend.

Roadmap

Onyxia Project Core Team Future Developments Roadmap

Want to know what we are up to?

Checkup our Milestones on GitHub:

Do not hesitate to vote or comment on the issues that are the most important to you. We prioritarize our work based on comunity feedback!

Or you can ask us on Slack, we're very prompt to respond!

user doc

Getting started with Onyxia

Using Onyxia (as a data scientist)

Start a service

Following is a documentation Onyxia when configured with the default service catalogs :

This collection of charts help users to launch many IDE with various binary stacks (python , R) with or without GPU support. Docker images are built and help us to give a homogeneous stack.

This collection of charts help users to launch many databases system. Most of them are based on .

This collection of charts help users to start automation tools for their datascience activity.

This collection of charts helps users to launch tools to visualize and share data insights.

The Onyxia user experience may be very different from one catalog of service to another.

The catalog defines what options are available though Onyxia.

Users can edit various parameters. Onyxia do some assertion based on the charts values schema and the configuration on the instance. For example some identity token can be injected by default (because Onyxia connect users to many APIs).

After launching a service, notes are shown to the user. He can retrieve those notes on the README button. Charts administrator should explain how to connect to the services (url , account) and what happens on deletion.

Now you want to learn how to setup your devloppement environement for day to day usage:

File browser

Users can manage their files on S3. There is no support for rename in S3 so don't be surprise. Onyxia is educational. Any action on the S3 browser in the UI is written in a console with a cli.

User can do the following S3 actions :

download files
upload files
delete files

Of course, in our default catalags there are all the necessary tools to connect to S3.

Our advice is to never download file to your container but directly ingest in memory the data.

Secret browser

Users can mange their secrets on Vault. There is also a cli console.

Onyxia use only a key value v2 secret engine in Vault. Users can store some secrets there and inject them in their services if configured by the helm chart.

Of course, in our default catalags there are all the necessary tools to connect to Vault.

Datascience Trainings and Tutorials

The Onyxia team maintain a catalog of training and tutorials with several practical exercices that can be performed on an Onyxia instance!

By default the when you open the trainings will be open on https://datalab.sspcloud.fr (our onyxia instance) but if you don't have a Datalab acount you can edit the urls of the practical exercises so you can run them on the instance you have access to.

Setting up your dev environment in Onyxia

In this video, we guide you through setting up your development environment in Onyxia. We demonstrate how to automatically clone your Git repository, install any missing dependencies, and open a port for your development server.

You can also find initialization scripts of interactive services here.

I forgot to show in the video that you can setup your GitHub/GitLab username and token in My Account -> External services.

This will enable Onyxia to clone private repos!

Community resources

You can find extra information on how to use Onyxia as a datascientist by checking out the community website of the french statistician workforce. It's in french though.

Want to share something you've done with Onyxia? You can click on "edit this page on GitHub" and submit a pull request!

v9

Admin doc

Install

hashtagOneliner

Kubernetes

GitOps

User authentication

hashtagDeploying Keycloak

hashtagConfiguring Keycloak

hashtagUpdating the Onyxia configuration

Data (S3)

hashtagCreating the 'minio' Keycloak client

hashtagDeploying MinIO

hashtagCreating the 'onyxia-minio' Keycloak client

hashtagUpdating the Onyxia configuration

Vault

Theme and branding

hashtagDefault looks

hashtagFrance

hashtagUltraviolet

Setting up group projects

Security consideration

hashtag1. Autolaunch Feature

hashtag2. Group Feature

Migration guides

v8 -> v9

v7 -> v8

v6 -> v7

hashtagThe THEME_ID parameter has been removed.

v5 -> v6

v4 -> v5

Migrating to the new helm repo

Contributors doc

The Web Application

Technical stack

hashtag

Architecture

hashtagMain rules

The REST API

Roadmap

user doc

Getting started with Onyxia

hashtagStart a service

hashtagFile browser

hashtagSecret browser

Datascience Trainings and Tutorials

Setting up your dev environment in Onyxia

Community resources

Security consideration

hashtag1. Autolaunch Feature

hashtag2. Group Feature

Migration guides

Install

hashtagOneliner

Roadmap

Community resources

Setting up your dev environment in Onyxia

Datascience Trainings and Tutorials

Vault

The Web Application

The REST API

v5 -> v6

Setting up group projects

GitOps

Data (S3)

hashtagCreating the 'minio' Keycloak client

hashtagDeploying MinIO

hashtagCreating the 'onyxia-minio' Keycloak client

hashtagUpdating the Onyxia configuration

v7 -> v8

v8 -> v9

Getting started with Onyxia

hashtagStart a service

hashtagFile browser

hashtagSecret browser

v4 -> v5

Migrating to the new helm repo

Theme and branding

hashtagDefault looks

hashtagFrance

Oneliner

Deploying Keycloak

Configuring Keycloak

Updating the Onyxia configuration

Creating the 'minio' Keycloak client

Deploying MinIO

Creating the 'onyxia-minio' Keycloak client

Updating the Onyxia configuration

Default looks

France

Ultraviolet

1. Autolaunch Feature

2. Group Feature

The `THEME_ID` parameter has been removed.

Main rules

Start a service

File browser

Secret browser

1. Autolaunch Feature

2. Group Feature

Oneliner

Creating the 'minio' Keycloak client

Deploying MinIO

Creating the 'onyxia-minio' Keycloak client

Updating the Onyxia configuration

Start a service

File browser

Secret browser

Default looks

France

Ultraviolet

Main rules

The `THEME_ID` parameter has been removed.

If you where using the `ultraviolet` theme:

If you where using the `verdant` theme:

Header parameters

Links in the header and the left bar

Assets must now be bundled

Keycloak Theme

Architecture

In practice

Another example: Recording user's GitLab token

How to deal with project switching

Deploying Keycloak

Configuring Keycloak

Updating the Onyxia configuration

For working on what the end user 👁

Onyxia-UI 🐔

MUI integration

🔡 Linking onyxia-ui in onyxia-web

tss-react 🐔

screen-scaler 🐔

Storybook

vite-envs 🐔

powerhooks 🐔

Avoiding useless re-render of Components

Measuring Components

Keycloakify 🐔

type-routes

i18nifty 🐔

Vite

For working on 🧠 of the App

clean-architecture 🐔

oidc-spa 🐔

EVT 🐔

Using your own catalogs (helm charts repositories)

Customizing your helm charts for Onyxia

[x-onyxia] overwriteDefaultWith

[x-onyxia] overwriteListEnumWith

[x-onyxia] overwriteSchemaWith

node selectors

rolebindings for IDE pods

resources for IDE

How to overwrite a schema or create a new one ?