Update docs to use JHub App Launcher

docs/docs/faq.md

@@ -167,5 +167,5 @@ If you have potential solutions or can help us move forward with updates to the
 <!-- Internal links -->
 
 [dask-tutorial]: tutorials/using_dask.md
-[selecting a profile]: how-tos/login-keycloak#3-selecting-a-profile
+[selecting a profile]: tutorials/login-keycloak#4-select-a-profile
 [pytorch best practices]: how-tos/pytorch-best-practices

docs/docs/how-tos/configure-keycloak-howto.md

@@ -186,5 +186,5 @@ Once complete, return to the **Users** section in the dashboard and add the rele
 
 <!-- internal links -->
 
-[keycloak-login]: login-keycloak
-[nebari-install]: /get-started/installing-nebari.md
+[keycloak-login]: /docs/tutorials/login-keycloak
+[nebari-install]: /docs/get-started/installing-nebari.md

docs/docs/how-tos/nebari-upgrade.md

@@ -225,7 +225,7 @@ The last two steps are:
 1. Change the Keycloak `root` user password, documented [here](./configure-keycloak-howto.md#change-keycloak-root-password)
 2. Import existing users, documented [here](./manual-backup.md#import-keycloak).
 
-For more details on this process, visit the [Keycloak docs section](./login-thru-keycloak-howto.md).
+For more details on this process, visit the [Keycloak docs section][login-keycloak].
 
 ### Known versions that require re-deployment
 
@@ -407,9 +407,12 @@ The last two steps are:
 1. Change the Keycloak `root` user password, documented [here](./configure-keycloak-howto.md#change-keycloak-root-password)
 2. Import existing users, documented [here](./manual-backup.md#import-keycloak).
 
-For more details on this process, visit the [Keycloak docs section](./login-thru-keycloak-howto.md).
+For more details on this process, visit the [Keycloak docs section][login-keycloak].
 
 ### Known versions that require re-deployment
 
 Version `v0.3.11` on AWS has an error with the Kubernetes config map. See [this GitHub discussion related to AWS K8s config maps](https://github.com/Quansight/nebari/discussions/841) for more details.
 :::
+
+<!-- Internal links -->
+[login-keycloak]: /docs/tutorials/login-keycloak

docs/docs/tutorials/login-with-keycloak.md

@@ -0,0 +1,121 @@
+---
+id: login-keycloak
+title: Authenticate and launch JupyterLab
+description: |
+  A step-by-step guide to logging into your Nebari instance and launching a JupyterLab pod.
+---
+
+# 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 login screen](/img/how-tos/nebari_login_screen.png)
+
+Nebari uses [Keycloak](https://www.keycloak.org/), 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][nebari-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][nebari-keycloak-add-user] 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](https://www.keycloak.org/docs/latest/server_admin/#_identity_broker) / authentication provider ([LDAP](https://pt.wikipedia.org/wiki/LDAP), [OAuth 2.0](https://oauth.net/2/), 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][nebari-keycloak] sections of the docs.
+
+In this example, Auth0 is the identity provider.
+To continue the login process,
+select the `Auth0` button and login.
+
+<p align="center">
+<img src="/img/tutorials/keycloak_nebari_login.png" alt="Nebari Keycloak auth screen - shows a form to provide username or password or to authenticate through Auth0" width="400"/>
+</p>
+
+## 3. Navigate the landing page
+
+:::note
+You may need to "Authorize access" to reach the home page:
+
+<p align="center">
+<img src="/img/tutorials/jhub-apps-authorize.png" alt="Authorize access page with an 'Authorize' button requesting access for JHub Apps, which is a Jupyter Service, to identify the user." width="80%"/>
+</p>
+:::
+
+Once authenticated, the **Nebari home page** opens.
+The home page, also referred to as "Landing page" or "JupyterHub launcher",
+lists Nebari's core **services** and allows you to create and share web apps.
+
+<!-- TODO: Link to app creation & sharing tutorial when available -->
+
+Click on the **"JupyterLab"** button under Services to start a server and launch JupyterLab:
+
+![Nebari home page with Services: JupyterLab, Argo, Users, Environments, Monitoring, VSCode; My Apps: JupyterLab (default JupyterLab instance); and Shared Apps.](/img/tutorials/nebari-home.png)
+
+:::warning
+This landing page was added recently and is in active development.
+You can follow the progress on [JHub App Launcher's GitHub repository][jhub-apps-gh].
+
+To go back to the legacy version, [disable the launcher in `nebari-config.yaml`][install-jhub-apps].
+:::
+
+### Legacy JupyterHub dashboard (v2023.12.1 or earlier)
+
+Nebari versions 2023.12.1 and earlier had a different landing page with core services listed in the top navigation bar:
+
+![Nebari dashboard main screen - displays a button "Start my server"](/img/how-tos/nebari_main_hub_page.png)
+
+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][profile-configuration].
+
+![Nebari select profile](/img/how-tos/nebari_select_profile.png)
+
+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 blue progress bar:
+
+![Nebari start server](/img/how-tos/nebari_server_start.png)
+
+<details>
+<summary>Optional: View Event log</summary>
+
+During this time you might see some log messages that detail the autoscaling process. Click the **Event Log** button to view them:
+
+![Nebari event log](/img/how-tos/keycloak_start_event_logs.png)
+
+</details>
+
+:::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][troubleshooting] for more information.
+:::
+
+Once launched, you use all the features of JupyterLab!
+
+<!-- Internal links -->
+
+[nebari-keycloak]: /docs/how-tos/configuring-keycloak
+[nebari-keycloak-add-user]: /docs/how-tos/configuring-keycloak#adding-a-nebari-user
+[install-jhub-apps]: /docs/how-tos/jhub-app-launcher#installation
+[profile-configuration]: /docs/explanations/profile-configuration
+[troubleshooting]: /docs/troubleshooting
+
+<!-- External links -->
+
+[jhub-apps-gh]: https://github.com/nebari-dev/jhub-apps

docs/docs/tutorials/using_dask.md

@@ -129,7 +129,7 @@ the data gets processed.
 
 :::note
 To use the dashboard for the first time, click on the dashboard link displayed in the Client UI.
-This opens a familiar Keycloak authentication page, where you can [sign-in the same way you authenticated into Nebari](/docs/how-tos/login-keycloak).
+This opens a familiar Keycloak authentication page, where you can [sign-in the same way you authenticated into Nebari](/docs/tutorials/login-keycloak).
 Dask's browser-based dashboard opens automatically.
 :::
 

docs/docs/welcome.mdx

@@ -23,9 +23,9 @@ import TabItem from '@theme/TabItem';
 
 If you are a data practitioner using Nebari for your day-to-day work, like data analysis, visualization, and more, the following path and pages will be useful for you.
 
-🔸 [Log-in to your team's Nebari instance, launch your JupyterLab server](./how-tos/login-keycloak), and use the IPython/Jupyter notebooks.
+🔸 [Log-in to your team's Nebari instance, launch your JupyterLab server](/docs/tutorials/login-keycloak), and use the IPython/Jupyter notebooks.
 
-🔸 Learn to [create new environments (kernels) using conda-store](./tutorials/creating-new-environments) if you need specific libraries.
+🔸 Learn to [create new environments (kernels) using conda-store](/docs/tutorials/creating-new-environments) if you need specific libraries.
 
 🔸 If you need to scale your work, [leverage Dask and Dask Gateway for parallel and distributed computing within Nebari][using-dask].
 
@@ -42,17 +42,17 @@ If you are setting up Nebari and managing the platform for your organization or
 
 🔸 Begin with the ["Get Started" documentation section][get-started] that includes complete instructions to install and deploy your own Nebari instance.
 
-🔸 The get started section will also take you to some "how-to guides" like the [deployment instructions for specific cloud-providers](./get-started/cloud-providers) and [DNS provisioning](./how-tos/domain-registry).
+🔸 The get started section will also take you to some "how-to guides" like the [deployment instructions for specific cloud-providers](/docs/get-started/cloud-providers) and [DNS provisioning](/docs/how-tos/domain-registry).
 
 🔸 After setup, [provide your team members access to your Nebari instance by configuring Keycloak][configure-keycloak].
 
-🔸 If you face issues or challenges, check out the [Troubleshooting section](./troubleshooting) and [GitHub Discussions][github-discussions] to learn from the community. You can also look into [debugging your deployment](./how-tos/debug-nebari).
+🔸 If you face issues or challenges, check out the [Troubleshooting section](/docs/troubleshooting) and [GitHub Discussions][github-discussions] to learn from the community. You can also look into [debugging your deployment](/docs/how-tos/debug-nebari).
 
-🔸 As a good security practice, [create and keep a manual backup](./how-tos/manual-backup) of your configurations and your team's work.
+🔸 As a good security practice, [create and keep a manual backup](/docs/how-tos/manual-backup) of your configurations and your team's work.
 
-🔸 To get the latest features, bug fixes, and security patches, [upgrade your Nebari instance](./how-tos/nebari-upgrade) regularly.
+🔸 To get the latest features, bug fixes, and security patches, [upgrade your Nebari instance](/docs/how-tos/nebari-upgrade) regularly.
 
-🔸 If or when you need to, you can [destroy the instance and all associated resources](./how-tos/nebari-destroy).
+🔸 If or when you need to, you can [destroy the instance and all associated resources](/docs/how-tos/nebari-destroy).
 
   </TabItem>
 
@@ -82,9 +82,9 @@ If you have any questions, you can reach the Nebari community on [GitHub Discuss
 
 New to Nebari? Start here to set up your own Nebari instance.
 
-> [Learn how to install and deploy Nebari from scratch →](./get-started/installing-nebari)
+> [Learn how to install and deploy Nebari from scratch →](/docs/get-started/installing-nebari)
 
-> Refer to [CLI commands in the Quick start →](./get-started/quickstart)
+> Refer to [CLI commands in the Quick start →](/docs/get-started/quickstart)
 
 <!-- TODO: All a link to Nebari 101 when it's ready. -->
 
@@ -190,4 +190,3 @@ Understand technical details of Nebari's architecture and how it works.
 [using-vscode]: ./how-tos/using-vscode
 [configure-keycloak]: ./how-tos/configuring-keycloak
 [create-dashboards]: ./tutorials/creating-cds-dashboard
-

docs/docusaurus.config.js

@@ -168,12 +168,6 @@ const config = {
           },
         ],
       },
-      announcementBar: {
-        id: "rename_announcement",
-        content:
-          '🪴 This project has been officially renamed to Nebari and migrated to the <a rel="noopener noreferrer" href="https://github.com/nebari-dev">nebari-dev</a> organization in GitHub.</br> Shall you encounter any issues or need support, you can find us in our <a rel="noopener noreferrer" href="https://github.com/nebari-dev/nebari"> new repository</a>.',
-        isCloseable: false,
-      },
       footer: {
         copyright: customFields.copyright,
         style: "dark",

docs/sidebars.js

@@ -42,6 +42,7 @@ module.exports = {
       label: "Tutorials",
       link: { type: "doc", id: "tutorials/index" },
       items: [
+        "tutorials/login-keycloak",
         "tutorials/using_dask",
         "tutorials/creating-cds-dashboard",
         "tutorials/creating-new-environments",
@@ -64,7 +65,6 @@ module.exports = {
         "how-tos/nebari-destroy",
         "how-tos/domain-registry",
         "how-tos/debug-nebari",
-        "how-tos/login-keycloak",
         "how-tos/configuring-keycloak",
         "how-tos/using-vscode",
         "how-tos/manual-backup",