1 of 13

v5

Install

Your Onyxia instance, today

Oneliner

TLDR. Here is how you can get an Onyxia instance running in a matter of seconds.

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

User guide

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.

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.

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.

Catalog of services

Every Onyxia instance may or may not have it's own catalog. There is three default 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.

You can always find the source of the catalog by clicking on the "contribute to the... " link.

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

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.

Technical doc

Willing to submit PRs on the Onyxia codebase?

The Web Application

The TypeScript App that runs in the browser.

This is the documentation for .

Architecture

Main rules

src/ui contains the React application, it's the UI of the app.
contains the 🧠 of the app.
- Nothing in the src/core directory should relate to React. A concept like react hooks for example is out of scope for the src/core directory.
- src/core should never import anything from src/ui, even types.

Architecture

Whenever we need to interact with the infrastructure we define a port in . A port is only a type definition. In our case the infrastructure is: the Keycloak server, the Vault server, the Minio server and a Kubernetes API (Onyxia-API).
In are the implementations of the ports. For each port we should have at least two implementations, a dummy and a real one. It enabled the app to still run, be it in degraded mode, if one piece of the infrastructure is missing. Say we don’t have a Vault server we should still be able to launch containers.

In practice

Let's say we want to create a new page in onyxia-web where users can type in a repo name and get the current number of stars the repo has on GitHub.

UPDATE: This video remain relevant but please not that the clean archi setup have been considerably improved in latest releases. have been created to explain it in detail.

Main take-way is that app have been renamed ui and lib have been renamed core.

You might wonder why some values, instead of being redux state, are returned by thunks functions.

For example, it might seem more natural to do:

Instead of what we actually do, which is:

However the rule is to never store as a redux state, values that are not susceptible to change. Redux states are values that we observe, any redux state changes should trigger a re-render of the React components that uses them. Conversely, there is no need to observe a value that will never change. We can get it once and never again, get it in a callback or wherever.

Now let's say we want the search to be restricted to a given GitHub organization. (Example: InseeFrLab.) The GitHub organization should be specified as an environment variable by the person in charge of deploying Onyxia. e.g.:

If no ORG_NAME is provided by the administrator, the app should always show 999 stars for any repo name queried.

Another example: Recording user's GitLab token

Currently users can save their GitHub Personal access token in their Onyxia account but not yet their GitLab token. Let's see how we would implement that.

How to deal with project switching

The easy action to take when the user selects another project is to simply reload the page (windows.location.reload()). We want to avoid doing this to enable what we call "hot projet swiping":

To implement this behavior you have to leverage the evtAction middleware from clean-redux. It enabled to register functions to be run when certain actions are dispatched.

Unlike the other video, the following one is voiced. Find the relevant code .

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

Data Explorer Evolution

Transforming the existing file browser into a comprehensive data explorer is a central aspect of our development roadmap. This enhancement aims to provide data scientists with immediate access to the initial rows of various file formats (including but not limited to parquet, CSV, and JSON) directly via the Onyxia-web interface. This will effectively integrate a basic SQL engine, DuckDB Wasm, for swift data access and manipulation.

User guide

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.

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

The catalog defines what options are available though Onyxia.

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.

Hashicorp maintains great tutorials for terraforming Kubernetes clusters on AWS, GCP or Azure.

Pick one of the three and follow the guide.

You can stop after the configure kubectl section.

Ingress controller

Deploy an ingress controller on your cluster:

The following command is .

For GCP use .

For Azure use .

DNS

Let's assume you own the domain name my-domain.net, for the rest of the guide you should replace my-domain.net by a domain you actually own.

Now you need to get the external address of your cluster, run the command

and write down the External IP assigned to the LoadBalancer.

Depending on the cloud provider you are using it can be an IPv4, an IPv6 or a domain. On AWS for example, it will be a domain like xxx.elb.eu-west-1.amazonaws.com.

If you see <pending>, wait a few seconds and try again.

Once you have the address, create the following DNS records:

If the address you got was an IPv4 (x.x.x.x), create a A record instead of a CNAME.

If the address you got was ans IPv6 (y:y:y:y:y:y:y:y), create a AAAA record.

https://onyxia.my-domain.net will be the URL for your instance of Onyxia. The URL of the services created by Onyxia are going to look like: https://<something>.lab.my-domain.net

You can customise "onyxia" and "lab" to your liking, for example you could chose datalab.my-domain.net and *.kub.my-domain.net.

SSL

In this section we will obtain a TLS certificate issued by using the commend line tool then get our ingress controller to use it.

If you are already familiar with certbot you're probably used to run it on a remote host via SSH. In this case you are expected to run it on your own machine, we'll use the DNS chalenge instead of the HTTP chalenge.

The obtained certificate needs to be renewed every three month.

To avoid the burden of having to remember to re-run the certbot command periodically you can setup and configure a on your cluster but that's out of scope for Onyxia.

You may need to delegate your DNS Servers to one of the supported .

Now we want to create a Kubernetes secret containing our newly obtained certificate:

Lastly, we want to tell our ingress controller to use this TLS certificate, to do so run:

This command will open your configured text editor, go to line 56 and add:

If you are on a Mac or Window computer you can install then enable Kubernetes.

Docker desktop isn't available on Linux, you can use instead.

Port Forwarding

You'll need to . It's done from the administration panel of your domestic internet Box. If you're on a corporate network, no luck for you I'm afraid.

helm repo add codecentric https://codecentric.github.io/helm-charts DOMAIN=my-domain.net POSTGRESQL_PASSWORD=xxxxx #Replace by a strong password, you will never need it. # Credentials for logging to https://auth.lab.$DOMAIN/auth KEYCLOAK_USER=admin KEYCLOAK_PASSWORD=yyyyyy cat << EOF > ./keycloak-values.yaml image: # We use the legacy variant of the image until codecentric update it's helm chart tag: "19.0.3-legacy" replicas: 1 extraInitContainers: | - name: realm-ext-provider image: curlimages/curl imagePullPolicy: IfNotPresent command: - sh args: - -c - | # There is a custom theme published alongside every onyxia-web release # The version of the Keycloak theme and the version of onyxia-web don't need # to match but you should update the theme from time to time. # https://github.com/InseeFrLab/onyxia-web/releases curl -L -f -S -o /extensions/onyxia.jar https://github.com/InseeFrLab/onyxia-web/releases/download/v2.29.4 /keycloak-theme.jar volumeMounts: - name: extensions mountPath: /extensions extraVolumeMounts: | - name: extensions mountPath: /opt/jboss/keycloak/standalone/deployments extraVolumes: | - name: extensions emptyDir: {} extraEnv: | - name: KEYCLOAK_USER value: $KEYCLOAK_USER - name: KEYCLOAK_PASSWORD value: $KEYCLOAK_PASSWORD - name: JGROUPS_DISCOVERY_PROTOCOL value: kubernetes.KUBE_PING - name: KUBERNETES_NAMESPACE valueFrom: fieldRef: apiVersion: v1 fieldPath: metadata.namespace - name: KEYCLOAK_STATISTICS value: "true" - name: CACHE_OWNERS_COUNT value: "2" - name: CACHE_OWNERS_AUTH_SESSIONS_COUNT value: "2" - name: PROXY_ADDRESS_FORWARDING value: "true" - name: JAVA_OPTS value: >- -Dkeycloak.profile=preview -XX:+UseContainerSupport -XX:MaxRAMPercentage=50.0 -Djava.net.preferIPv4Stack=true -Djava.awt.headless=true ingress: enabled: true servicePort: http annotations: kubernetes.io/ingress.class: nginx ## Resolve HTTP 502 error using ingress-nginx: ## See https://www.ibm.com/support/pages/502-error-ingress-keycloak-response nginx.ingress.kubernetes.io/proxy-buffer-size: 128k rules: - host: "auth.lab.$DOMAIN" paths: - path: / pathType: Prefix tls: - hosts: - auth.lab.$DOMAIN postgresql: postgresqlPassword: $POSTGRESQL_PASSWORD EOF helm install keycloak codecentric/keycloak -f keycloak-values.yaml

serviceAccount: clusterAdmin: true ingress: enabled: true annotations: kubernetes.io/ingress.class: nginx hosts: - host: onyxia.my-domain.net web: env: KEYCLOAK_REALM: datalab KEYCLOAK_URL: https://auth.lab.my-domain.net/auth TERMS_OF_SERVICES: | { "en": "https://www.sspcloud.fr/tos_en.md", "fr": "https://www.sspcloud.fr/tos_fr.md" } api: env: authentication.mode: openidconnect keycloak.realm: datalab keycloak.auth-server-url: https://auth.lab.my-domain.net/auth regions: [ { "id":"demo", "name":"Demo", "description":"This is a demo region, feel free to try Onyxia !", "services":{ "type":"KUBERNETES", "singleNamespace": false, "namespacePrefix":"user-", "usernamePrefix":"oidc-", "groupNamespacePrefix":"projet-", "groupPrefix":"oidc-", "authenticationMode":"admin", "expose":{ "domain":"lab.my-domain.net" }, "monitoring":{ "URLPattern":"todo" }, "cloudshell":{ "catalogId":"inseefrlab-helm-charts-datascience", "packageName":"cloudshell" }, "initScript":"https://inseefrlab.github.io/onyxia/onyxia-init.sh" }, "data":{ "S3":{ - "URL":"todo", + "type": "minio", + "URL": "https://minio.lab.my-domain.net", + "region": "us-east-1", + "bucketPrefix": "oidc-", + "groupBucketPrefix": "projet-", + "bucketClaim": "preferred_username", + "defaultDurationSeconds": 86400, + "keycloakParams": + { + "URL": "https://auth.lab.my-domain.net/auth", + "realm": "datalab", + "clientId": "onyxia-minio", + }, + "acceptBucketCreation": true, "monitoring":{ "URLPattern":"minio" } } }, "auth":{ "type":"openidconnect" }, "location":{ "lat":48.8164, "long":2.3174, "name":"Montrouge (France)" } } ]

Architecture

Main rules

src/ui contains the React application, it's the UI of the app.
contains the 🧠 of the app.
- Nothing in the src/core directory should relate to React. A concept like react hooks for example is out of scope for the src/core directory.
- src/core should never import anything from src/ui, even types.

Architecture

Whenever we need to interact with the infrastructure we define a port in . A port is only a type definition. In our case the infrastructure is: the Keycloak server, the Vault server, the Minio server and a Kubernetes API (Onyxia-API).
In are the implementations of the ports. For each port we should have at least two implementations, a dummy and a real one. It enabled the app to still run, be it in degraded mode, if one piece of the infrastructure is missing. Say we don’t have a Vault server we should still be able to launch containers.

In practice

Let's say we want to create a new page in onyxia-web where users can type in a repo name and get the current number of stars the repo has on GitHub.

UPDATE: This video remain relevant but please not that the clean archi setup have been considerably improved in latest releases. have been created to explain it in detail.

Main take-way is that app have been renamed ui and lib have been renamed core.

You might wonder why some values, instead of being redux state, are returned by thunks functions.

For example, it might seem more natural to do:

Instead of what we actually do, which is:

If no ORG_NAME is provided by the administrator, the app should always show 999 stars for any repo name queried.

Another example: Recording user's GitLab token

Currently users can save their GitHub Personal access token in their Onyxia account but not yet their GitLab token. Let's see how we would implement that.

How to deal with project switching

The easy action to take when the user selects another project is to simply reload the page (windows.location.reload()). We want to avoid doing this to enable what we call "hot projet swiping":

To implement this behavior you have to leverage the evtAction middleware from clean-redux. It enabled to register functions to be run when certain actions are dispatched.

Unlike the other video, the following one is voiced. Find the relevant code .

onyxia: web: env: - KEYCLOAK_URL: https://auth.lab.sspcloud.fr/auth - KEYCLOAK_REALM: sspcloud api: env: - keycloak.resource: onyxia - keycloak.realm: sspcloud - keycloak.auth-server-url: https://auth.lab.sspcloud.fr/auth - keycloak.ssl-required: external - keycloak.public-client: "true" - keycloak.enable-basic-auth: "true" - keycloak.bearer-only: "true" + oidc.issuer-uri: "https://auth.lab.sspcloud.fr/auth/realms/sspcloud" + oidc.clientID: "onyxia" + oidc.audience: "onyxia" authentication.mode: "openidconnect" regions: [ { "id": "paris", "services": { - "authenticationMode": "admin", + "authenticationMode": "serviceAccount", "k8sPublicEndpoint": { "URL": "https://apiserver.kub.sspcloud.fr", - "keycloakParams": { - "URL": "https://auth.lab.sspcloud.fr/auth", - "realm": "sspcloud", - "clientId": "onyxia" - }, + "oidcConfiguration": { + "issuerURI": "https://auth.lab.sspcloud.fr/auth/realms/sspcloud", + "clientID": "onyxia-k8s-apiserver", + } } }, "data": { "S3": { - "keycloakParams": { - "URL": "https://auth.lab.sspcloud.fr/auth", - "realm": "sspcloud", - "clientId": "onyxia-minio", - } + "oidcConfiguration": { + "issuerURI": "https://auth.lab.sspcloud.fr/auth/realms/sspcloud", + "clientID": "onyxia-minio", + } } }, "vault": { "URL": "https://vault.lab.sspcloud.fr", - "keycloakParams": { - "URL": "https://auth.lab.sspcloud.fr/auth", - "realm": "sspcloud", - "clientId": "onyxia-vault", - } + "oidcConfiguration": { + "URL": "https://auth.lab.sspcloud.fr/auth/realms/sspcloud", + "clientID": "onyxia-vault" + } } } ]

"git": { "description": "Git user configuration", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Add git config inside your environment", "default": true }, "name": { "type": "string", "description": "user name for git", "default": "", "x-onyxia": { "overwriteDefaultWith": "git.name" }, "hidden": { "value": false, "path": "git/enabled" } }, "email": { "type": "string", "description": "user email for git", "default": "", "x-onyxia": { "overwriteDefaultWith": "git.email" }, "hidden": { "value": false, "path": "git/enabled" } }, "cache": { "type": "string", "description": "duration in seconds of the credentials cache duration", "default": "", "x-onyxia": { "overwriteDefaultWith": "git.credentials_cache_duration" }, "hidden": { "value": false, "path": "git/enabled" } }, "token": { "type": "string", "description": "personal access token", "default": "", "x-onyxia": { "overwriteDefaultWith": "git.token" }, "hidden": { "value": false, "path": "git/enabled" } }, "repository": { "type": "string", "description": "Repository url", "default": "", "hidden": { "value": false, "path": "git/enabled" } }, "branch": { "type": "string", "description": "Brach automatically checkout", "default": "", "hidden": { "value": "", "path": "git/repository" } } } },

export type XOnyxiaParams = { /** * This is where you can reference values from the onyxia context so that they * are dynamically injected by the Onyxia launcher. * * Examples: * "overwriteDefaultWith": "user.email" * "overwriteDefaultWith": "{{project.id}}-{{k8s.randomSubdomain}}.{{k8s.domain}}" */ overwriteDefaultWith?: string; hidden?: boolean; readonly?: boolean; useRegionSliderConfig?: string; }; export type XOnyxiaContext = { user: { idep: string; name: string; email: string; password: string; ip: string; darkMode: boolean; }; project: { id: string; password: string; basic: string; }; git: { name: string; email: string; credentials_cache_duration: number; token: string | undefined; }; vault: { VAULT_ADDR: string; VAULT_TOKEN: string; VAULT_MOUNT: string; VAULT_TOP_DIR: string; }; kaggleApiToken: string | undefined; s3: { AWS_ACCESS_KEY_ID: string; AWS_SECRET_ACCESS_KEY: string; AWS_SESSION_TOKEN: string; AWS_DEFAULT_REGION: string; AWS_S3_ENDPOINT: string; AWS_BUCKET_NAME: string; port: number; }; region: { defaultIpProtection: boolean | undefined; defaultNetworkPolicy: boolean | undefined; allowedURIPattern: string; kafka: | { url: string; topicName: string; } | undefined; tolerations: unknown[] | undefined; from: unknown[] | undefined; nodeSelector: Record<string, unknown> | undefined; startupProbe: Record<string, unknown> | undefined; sliders: Record< string, { sliderMin: number; sliderMax: number; sliderStep: number; sliderUnit: string; } >; resources: | { cpuRequest?: `${number}${string}`; cpuLimit?: `${number}${string}`; memoryRequest?: `${number}${string}`; memoryLimit?: `${number}${string}`; disk?: `${number}${string}`; gpu?: `${number}`; } | undefined; }; k8s: { domain: string; ingressClassName: string | undefined; ingress: boolean | undefined; route: boolean | undefined; istio: | { enabled: boolean; gateways: string[]; } | undefined; randomSubdomain: string; initScriptUrl: string; }; proxyInjection: | { httpProxyUrl: string | undefined; httpsProxyUrl: string | undefined; noProxy: string | undefined; } | undefined; packageRepositoryInjection: | { cranProxyUrl: string | undefined; condaProxyUrl: string | undefined; packageManagerUrl: string | undefined; pypiProxyUrl: string | undefined; } | undefined; certificateAuthorityInjection: | { cacerts: string | undefined; pathToCaBundle: string | undefined; } | undefined; };

{ "$schema": "http://json-schema.org/schema#", "type": "object", "properties": { "resources": { "description": "Your service will have at least the requested resources and never more than its limits. No limit for a resource and you can consume everything left on the host machine.", "type": "object", "properties": { "limits": { "description": "max resources", "type": "object", "properties": { "nvidia.com/gpu": { "description": "GPU to allocate to this instance. This is also requested", "type": "string", "default": "0", // Will be overwritten by "1" "render": "slider", "sliderMin": 0, // Will be overwritten by 1 "sliderMax": 3, // Will be overwritten by 4 "sliderStep": 1, // Will be overwritten by 1 "sliderUnit": "", // Will be overwritten by "" "x-onyxia": { "overwriteDefaultWith": "region.resources.gpu", "useRegionSliderConfig": "gpu" // 👀 } }, "cpu": { "description": "The maximum amount of cpu", "title": "CPU", "type": "string", "default": "30000m", "render": "slider", "sliderMin": 50, "sliderMax": 40000, "sliderStep": 50, "sliderUnit": "m", "sliderExtremity": "up", "sliderExtremitySemantic": "Maximum", "sliderRangeId": "cpu", "x-onyxia": { "overwriteDefaultWith": "region.resources.cpuLimit", "useRegionSliderConfig": "cpu" } }, "memory": { "description": "The maximum amount of memory", "title": "Memory", "type": "string", "default": "50Gi", "render": "slider", "sliderMin": 1, "sliderMax": 200, "sliderStep": 1, "sliderUnit": "Gi", "sliderExtremity": "up", "sliderExtremitySemantic": "Maximum", "sliderRangeId": "memory", "x-onyxia": { "overwriteDefaultWith": "region.resources.memoryLimit", "useRegionSliderConfig": "memory" } } } } } } } }

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.

Typescript

We are fully committed on keeping everything type safe. If you are a seasoned developer but not fully comfortable with TypeScript yet a good way to get you quickly up to speed is to go through the of the official website.

You can skip anything related to class we don't do OOP in the project.

tsafe 🐔

We also heavily rely on . It's a collection of utilities that help write cleaner TypeScript code. It is crutial to understand at least , , and to be able to contribute on the codebase.

TS-CI 🐔

We try, whenever we see an opportunity for it, to publish as standalone NPM module chunks of the code we write for Onyxia-web. It help keep the complexity in check. We use TS-CI as a starter for everything we publish on NPM.

For working on what the end user 👁

Anything contained in the directory.

Onyxia-UI 🐔

The UI toolkit used in the project, you can find the setup of in onyxia-web here: .

integration

is fully compatible with .

Onyxia-UI offers but you can also use components in the project, their aspect will automatically be adapted to blend in with the theme.

🎨 Palettes

We currently offers builtin support for :

France:
Ultraviolet:
Verdant:

You can also .

🔡 Fonts

The fonts are loaded in the . It's important to keep it that way for Keycloakify.

🔡 Linking onyxia-ui in onyxia-web

To release a new version of . You just need to bump the and push. will automate publish .

If you want to test some changes made to onyxia-ui in onyxia-web before releasing a new version of onyxia-ui to NPM you can link locally onyxia-ui in onyxia-web.

Now you can make changes in ~/github/onyxia/ui/and see the live updates.

If you want to install/update some dependencies, you must remove the node_modules, do you updates, then link again.

tss-react 🐔

The library we use for styling.

Rules of thumbs when it comes to styling:

Every component should acceptprop it should always .
A component should not size or position itself. It should always be the responsibility of the parent component to do it. In other words, you should never have height, width, top, left, right,

screen-scaler 🐔

Onyxia is mostly used on desktop computer screens. It's not worth the effort to create a fully flege responsive design for the UI. screen-scaler enables us to design for a sigle canonical screen size. The library take charge of scaling/shrinking the image. depending on the real size of the screen. It also asks to rotate the screen when the app is rendered in protrait mode.

Storybook

It enables us to test the graphical components in isolation. .

To launch Storybook locally run the following command:

cra-envs 🐔

We need to be able to do:

Then, somehow, access OIDC_URL in the code like process.env["OIDC_URL"].

In theory it shouldn't be possible, onyxia-web is an SPA, it is just static JS/CSS/HTML. If we want to bundle values in the code, we should have to recompile. But this is where comes into play.

It enables to run onyxia-web again a specific infrastructure while keeping the app docker image generic.

Checkout :

All the accepted environment variables are defined here: . They are all prefixed with REACT_APP_ to be compatible . Default values are defined in this file.
Only in development (yarn start) is also loaded and have priority over .env

Please try not to access the environment variable to liberally through out the code. In principle they should only be accessed . We try to keep things as much as possible.

powerhooks 🐔

It's a collection general purpose react hooks. Let's document the few use cases you absolutely need to understand:

Avoiding useless re-render of Components

For the sake of performance we enforce that every component be wrapped into . It makes that a component only re-render if one of their prop has changed.

However if you use inline functions or as callbacks props your components will re-render every time anyway:

We always use for callback props. And for callback prop in lists.

Measuring Components

It is very handy to be able to get the height and the width of components dynamically. It prevents from having to hardcode dimension when we don’t need to. For that we use ``

Keycloakify 🐔

It's a build tool that enables to implement the login and register pages that users see when they are redirected to Keycloak for authentication.

If the app is being run on Keycloak the isn't undefined and it means shat we should render the login/register pages.

If you want to test, uncomment and run yarn start. You can also test the login pages in a local keycloak container by running yarn keycloak. All the instructions will be printed on the console.

The keycloak-theme.jar file is automatically and by the CI.

type-routes

The library we use for routing. It's like but type safe.

i18nifty 🐔

For internalization and translation.

create-react-app

We plane to move to Vite when will support it.

The project is a non-ejected using (you can find the template repo that was used as a base for this project).

We use instead of the default react-scripts to be able to use custom Webpack plugins without having to eject the App. The custom webpack plugins that we use are defined here . Currently we only one we use is .

For working on 🧠 of the App

Anything contained in the directory.

redux-clean-architecture 🐔

The framework used to implement strict separation of concern betwen the UI and the Core and high modularity of the code.

EVT 🐔

EVT is an event management library (like is).

A lot of the things we do is powered under the hood by EVT. You don't need to know EVT to work on onyxia-web however, in order to demystify the parts of the codes that involve it, here are the key ideas to take away:

If we need to perform particular actions when a value gets changed, we use.
We use Ctxto detaches event handlers when we no longer need them. (See line 108 on )
In React, we use the hook to work with DOM events.

v5

Install

hashtagOneliner

User guide

hashtagStart a service

hashtagFile browser

hashtagSecret browser

Catalog of services

Security consideration

hashtag1. Autolaunch Feature

hashtag2. Group Feature

Migration guides

v4 -> v5

Migrating to the new helm repo

Technical doc

The Web Application

Architecture

hashtagMain rules

hashtagArchitecture

hashtagIn practice

hashtagAnother example: Recording user's GitLab token

hashtagHow to deal with project switching

The REST API

Roadmap

hashtagData Explorer Evolution

Technical doc

Security consideration

hashtag1. Autolaunch Feature

hashtag2. Group Feature

The Web Application

The REST API

User guide

hashtagStart a service

hashtagFile browser

hashtagSecret browser

Install

hashtagOneliner

Migration guides

hashtagProvision a Kubernetes cluster

hashtagInstalling Onyxia using helm

hashtagEnabling user authentication

hashtagS3 Storage

hashtagCreate a Keycloak client for Accessing Keycloak

hashtagInstall MinIO

hashtagCreate a Keycloak Client for Onyxia/MinIO

hashtagUpdate Onyxia

hashtagVault

Roadmap

hashtagData Explorer Evolution

hashtagExpanded S3 Management Options

Architecture

hashtagMain rules

hashtagArchitecture

hashtagIn practice

hashtagAnother example: Recording user's GitLab token

hashtagHow to deal with project switching

v4 -> v5

Migrating to the new helm repo

Catalog of services

hashtagDefining region scoped resources limit

Technical stack

hashtagTypescript

hashtagtsafe 🐔

hashtagTS-CI 🐔

hashtagFor working on what the end user 👁

hashtagOnyxia-UI 🐔

hashtag integration

hashtag🎨 Palettes

hashtag🔡 Fonts

hashtag🔡 Linking onyxia-ui in onyxia-web

hashtagtss-react 🐔

hashtagscreen-scaler 🐔

hashtagStorybook

hashtagcra-envs 🐔

hashtagpowerhooks 🐔

hashtagAvoiding useless re-render of Components

hashtagMeasuring Components

hashtagKeycloakify 🐔

hashtagtype-routes

hashtagi18nifty 🐔

Oneliner

Start a service

File browser

Secret browser

1. Autolaunch Feature

2. Group Feature

Main rules

Architecture

In practice

Another example: Recording user's GitLab token

How to deal with project switching

Data Explorer Evolution

1. Autolaunch Feature

2. Group Feature

Start a service

File browser

Secret browser

Oneliner

Provision a Kubernetes cluster

Installing Onyxia using helm

Enabling user authentication

S3 Storage

Create a Keycloak client for Accessing Keycloak

Install MinIO

Create a Keycloak Client for Onyxia/MinIO

Update Onyxia

Vault

Data Explorer Evolution

Expanded S3 Management Options

Main rules

Architecture

In practice

Another example: Recording user's GitLab token

How to deal with project switching

Defining region scoped resources limit

Typescript

tsafe 🐔

TS-CI 🐔

For working on what the end user 👁

Onyxia-UI 🐔

integration

🎨 Palettes

🔡 Fonts

🔡 Linking onyxia-ui in onyxia-web

tss-react 🐔

screen-scaler 🐔

Storybook

cra-envs 🐔

powerhooks 🐔

Avoiding useless re-render of Components

Measuring Components

Keycloakify 🐔

type-routes

i18nifty 🐔

create-react-app

For working on 🧠 of the App

redux-clean-architecture 🐔

EVT 🐔