Authenticate and launch JupyterLab

This guide provides a basic overview of how to log in to your Nebari instance (through Keycloak) and launch JupyterLab on a new server (ie., machine).

1. Connect to your Nebari instance

Navigate to the instance homepage.

Once on the site, you will be prompted to log in, similar to the login page shown in the image below.

Nebari uses Keycloak, an open-source identity and access management tool. Keycloak is a centralized location for administrators to add new users, create user groups and update roles. For more information, see the How to Configure Keycloak docs.

🔥warning

Nebari does not create a "regular" user for you during deployment, it only creates the root Keycloak admin user. The following steps assume that your Nebari administrator has already created a Keycloak user in the Keycloak admin console for you. If not, follow the steps in Adding new users to Keycloak to create a Keycloak user.

2. Authenticate with your provider

At this stage, it is a little challenging to provide thorough instructions because the particulars will depend on your identity provider / authentication provider (LDAP, OAuth 2.0, passwordless authentication, password-based authentication and many others).

For more information on how to configure Keycloak, and add new users, review the How to configure Keycloak sections of the docs.

In this example, Auth0 is the identity provider. To continue the login process, select the Auth0 button and login.

3. Navigate the landing page

ℹ️note

You may need to "Authorize access" to reach the home page:

Once authenticated, the Nebari home page opens. The home page, also referred to as "Landing page", "JupyterHub launcher", or "App Launcher", lists Nebari's core services and allows you to create and share web apps.

Click on the "JupyterLab" button under "Services" to start a server and launch JupyterLab:

🔥warning

This landing page was added recently and is in active development. You can follow the progress on JHub App Launcher's GitHub repository.

To go back to the legacy version, disable the launcher in nebari-config.yaml.

Launch a new server

Landing page to Launch server:

Click on the Launch Server button to select a profile and launch JupyterLab.

ℹ️note

Nebari versions 2023.12.1 and earlier had a different landing page with core services listed in the top navigation bar: In which case, click on the Start My Server button to select a profile and launch JupyterLab.

4. Select a profile

The customized profiles (also called "instances", "servers" or "machines") will give you access to fixed cloud resources as mentioned in the list.

These options are configured by your administrator, learn more in the Profile Configuration documentation.

Select an appropriate profile and click "Start".

5. Start your server

JupyterLab starts to launch.

This step may take up to several minutes due to Nebari use of autoscaling under the hood. Ultimately this autoscaling feature helps reduce costs when the cluster is idle.

A successful launch process shows a purple progress bar:

Optional: View Event log

During this time you might see some log messages that detail the autoscaling process. Click the Event Log button to view them:

🔥warning

• The starting up sequence can take up to several minutes, depending on the size of the cluster. If the server is not accessible after 10 minutes, an error will be shown, and you will be redirected to the Home page. Please check the troubleshooting docs for more information.
• The Event logs may include warnings about "[Warning] 0/2 nodes are available: 2 node(s) didn't match Pod's node affinity/selector ..." . This is normal behaviour as cluster sometimes need to expand in order to start the server.
• Warning such as "[Warning]" Unable to retrieve some image pull secrets ..." can also be safely ignored.

Once your server is ready, you will be redirected to JupyterLab!