1 of 1

Install

Your Onyxia instance, today

Oneliner

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

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

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

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

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.

Step by step installation guide

In this section, we will set up Onyxia from the ground up, along with all the associated technologies. This includes MinIO for S3, Keycloak for OIDC, and Vault for managing secrets.

Provision a Kubernetes cluster

First you'll need a Kubernetes cluster. If you have one already you can skip this section.

Hashicorp maintains great tutorials for Kubernetes clusters on , or .

Pick one of the three and follow the guide.

You can stop after the .

Ingress controller

Deploy an ingress controller on your cluster:

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

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.

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.

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.

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.

In this section we assume that:

You have a Kubernetes cluster and kubectl configured
onyxia.my-domain.net and *.lab.my-domain.net are pointing to your cluster's external address. my-domain.net being a domain that you own. You can customise "onyxia" and "lab" to your liking, for example you could chose datalab.my-domain.net and *.kub.my-domain.net.

You can now access https://onyxia.my-domain.net and start services. Congratulations! 🥳

At the moment there is no authentication process, everyone can access our platform and and start services.

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

For deploying our Keycloak we use .

You can now login to the administration console of https://auth.lab.my-domain.net and login using the credentials you have defined with KEYCLOAK_USER and KEYCLOAK_PASSWORD.

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.

Update the onyxia-values.yaml file that you created previously, don't forget to replace all the occurence of my-domain.net by your actual domain.

Don't forget as well to remplace the terms of services of the by your own terms of services. CORS should be enabled on those .md links (Access-Control-Allow-Origin: *).

Now that you have updated onyxia-values.yaml restart onyxia-web with the new configuration.

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

Onyxia-web use to get token and empowered user with storage features. We support any S3 storage compatible with this API. In this context, we are using , which is compatible with the Amazon S3 storage service and we demonstrate how to integrate it with Keycloak.

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

Create a client called "minio".

Client ID: minio
Client Protocol: openid-connect
Root URL: https://minio.lab.my-domain.net/

Complete the content of client "minio" with the following values.

Access Type: confidential
Valid Redirect URIs (two values are required): https://minio.lab.my-domain.net/* and https://minio-console.lab.my-domain.net/*
Web origins: *

Save the content, a new tab called Credentials must be appear. Navigate to Credentials tab and copy the secret value for the next section.

Navigate to Mappers tab and create a protocol Mapper.

Name: policy
Mapper Type: Hardcoded claim

Complete the content of Mapper "policy" with the following values.

Token Claim Name: policy
Claim value: stsonly
Add to ID token: on

We recommand you to follow for this installation and you must activate OIDC authentification. We will use the official Helm in this tutorial. All Helm configuration values can be found within this .

Replace COPY_SECRET_FROM_KEYCLOAK_MINIO_CLIENT by the secret value defined into the "minio" Keycloak client (see previous section).

MinIO is now deployed and is accessible on the console url.

By default, there are 16 MinIO containers running. If this number is too large for your Kubernetes cluster, you can limit it by configuring the 'replicas' key.

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 complexe 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.

From "datalab" realm, create a client called "onyxia-minio"

Client ID: onyxia-minio
Client Protocol: openid-connect
Root URL: https://onyxia.my-domain.net/

Complete the content of client "onyxia-minio" with the following values.

Access Type: public
Valid Redirect URIs: https://onyxia.my-domain.net/*
Web origins: *

Save the content and navigate to Mappers tab and create two protocol Mappers.

Create the first Mapper called "policy".

Token Name: policy
Mapper Type: Hardcoded claim
Token Claim Name: policy

Create the second Mapper called "audience-minio".

Token Name: audience-minio
Mapper Type: Audience
_Included Custom Audience _: minio

S3 storage is configured inside a region in Onyxia api. You have some options to configure this storage and let inform Onyxia web all needed informations how to generate those tokens : keycloak parameters to access storage API, duration of STS tokens, bucket name with a standard prefix and a claim in the user JWT token to generate a unique identifiant for this bucket name, whether Onyxia-web should try to to create this bucket silently or not. There is also options for projects. You should look all options for the version of your need on

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 need 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)

Create a client called "vault"

Root URL: https://vault.lab.my-domain.net/
Valid redirect URIs: https://vault.lab.my-domain.net/*
Web origins: *

TODO;

Install

Your Onyxia instance, today

Oneliner

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

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

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

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

Step by step installation guide

In this section, we will set up Onyxia from the ground up, along with all the associated technologies. This includes MinIO for S3, Keycloak for OIDC, and Vault for managing secrets.

Provision a Kubernetes cluster

First you'll need a Kubernetes cluster. If you have one already you can skip this section.

Hashicorp maintains great tutorials for Kubernetes clusters on , or .

Pick one of the three and follow the guide.

You can stop after the .

Ingress controller

Deploy an ingress controller on your cluster:

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

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.

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.

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.

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.

In this section we assume that:

You have a Kubernetes cluster and kubectl configured
onyxia.my-domain.net and *.lab.my-domain.net are pointing to your cluster's external address. my-domain.net being a domain that you own. You can customise "onyxia" and "lab" to your liking, for example you could chose datalab.my-domain.net and *.kub.my-domain.net.

You can now access https://onyxia.my-domain.net and start services. Congratulations! 🥳

At the moment there is no authentication process, everyone can access our platform and and start services.

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

For deploying our Keycloak we use .

You can now login to the administration console of https://auth.lab.my-domain.net and login using the credentials you have defined with KEYCLOAK_USER and KEYCLOAK_PASSWORD.

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