Authenticate and launch JupyterLab

Phase out notice

Nebari is evolving. The original Nebari project is now called Nebari Classic, and is in maintenance mode.

We'll continue to provide security updates and key bug fixes; however, no new features are planned at this time. We're using the lessons learned from Nebari Classic to build a new Nebari ecosystem of tools, on a more robust foundation with a modular architecture. Nebari Classic's maintenance window will remain open until the new architecture reaches stability and feature parity, and current users are able to migrate, expected through the end of 2026.

See the current Nebari documentation for details on the new platform.

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. The text on this screen is configurable so your deployment may look slightly different.

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.

Caution

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 "Quick Access" to start a server and launch JupyterLab:

Caution

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

After clicking "Start", your JupyterLab instance starts to launch.

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

A progress bar is shown while the server is being set up:

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:

Caution

• 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 the 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!