Information	Links
Project
Community

Custom Nebari JupyterHub template

This repository contains a custom JupyterHub template for Nebari. This template overrides the default JupyterHub templates in https://github.com/jupyterhub/jupyterhub/tree/main/share/jupyterhub/templates.

For more details on JupyterHub templates and how they can be used check the official JupyterHub documentation.

• Custom Nebari JupyterHub template
  • Development 👩🏻‍💻
    • Prerequisites
    • Setting your development environment
  • Using nebari_jupyterhub_theme on your JupyterHub instance 📦
  • Architecture 🏗
  • Contributing to nebari-nebari_jupyterhub_theme👩‍💻
  • Code of Conduct 📖
  • License 📄

Development 👩🏻‍💻

Prerequisites

• Python >= 3.8

• We use Hatch for development and publishing of the Nebari JupyterHub theme.

  We recommend you install hatch through pipx as it modifies the Python environment in which this is installed (for more details, see the Hatch documentation)

  pipx install hatch
  

• hatch-conda plugin. To install:

  pipx install hatch-conda
  

Setting your development environment

1. Make a fork of the Nebari JupyterHub theme repository on your personal GitHub account.

2. Clone this repository to your local computer:

   git clone https://github.com/<your-username>/nebari-jupyterhub-theme.git
   

3. From the root of the project, create a new development environment with hatch:

   hatch env create
   

   This will create a new development environment with all the dependencies needed for development. It will also install nebari_jupyterhub_theme in development mode. You can verify that your development environment is correctly set up by running the following command:

   $ hatch env show
                          Standalone
   ┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
   ┃ Name    ┃ Type    ┃ Dependencies            ┃ Scripts ┃
   ┡━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
   │ default │ virtual │                         │         │
   ├─────────┼─────────┼─────────────────────────┼─────────┤
   │ dev     │ virtual │ configurable-http-proxy │ render  │
   │         │         │ jupyterhub              │         │
   │         │         │ jupyterlab              │         │
   │         │         │ nodejs                  │         │
   └─────────┴─────────┴─────────────────────────┴─────────┘
   

4. Initialize a new shell within the development environment:

   hatch --env dev shell
   

   To leave the environment you can type exit on your terminal.

5. Initialize a JupyterHub instance for development:

   hatch run dev:render
   

   This command will start JupyterHub with the --config option pointing to test_jupyterhub_config.py. You should be able to head to http://127.0.0.1:8081 on your web browser and see the JupyterHub instance running.

   

   Note From here you can log in with any username and the password set in the c.DummyAuthenticator.password configuration option in test_jupyterhub_config.py. Also note not all the extensions and integrations are available in this dev mode.

6. You can now modify the templates and the style.css file and see the changes reflected in the JupyterHub instance without having to restart the server.

Note The values specified in c.JupyterHub.template_vars will overwrite the default values set in nebari_jupyterhub_theme/templates

The release process for this package is documented in RELEASE.md.

Using nebari_jupyterhub_theme on your JupyterHub instance 📦

1. Install nebari_jupyterhub_theme:

   pip install nebari_jupyterhub_theme
   

   Note If you already have a JupyterHub configuration file you can jump to the next step. Otherwise, follow the instructions in the JupyterHub documentation to generate a configuration file first.

2. Add the following to you JupyterHub configuration file to pick up the new jinja2 templates directory and static files:

   from nebari_jupyterhub_theme import theme_extra_handlers, theme_template_paths
   
   c.JupyterHub.extra_handlers = theme_extra_handlers
   
   c.JupyterHub.template_paths = theme_template_paths
   

3. Optional - if you need to further customize the UI you can modify the template_vars within your JupyterHub config file by adding the following lines to it:

   # minimal configuration example overwriting the default values in the nebari_jupyterhub_theme
   c.JupyterHub.template_vars = {
    "hub_title": "Welcome to Nebari",
    "logo": "/hub/custom/images/Nebari-logo-square.svg",
    "primary_color": "#cb39ed",
    "secondary_color": "#2bd1c5",
   

The available configuration variables are:

• hub_title: The title of the JupyterHub instance. This will be displayed in the header of the login page. (H1 heading, default: Welcome to Nebari)
• hub_subtitle: Subtitle shown under the main instance Title. (H2 heading, default: "")
• welcome: Welcome message on the login page (default: Welcome to Nebari. For more information about Nebari, visit <a href="https://nebari.dev/">https://nebari.dev</a>)
• logo: Logo displayed on the navbar (default: Nebari logomark)
• primary_color: Primary color (default: #9e17b7)
• secondary_color: Secondary color (default: #2bd1c5)
• accent_color: Accent color (default: #eda61d)
• text_color: Text color (default: #1c1d26)
• h1_color: H1 color, main Title in login page (default: #0f1015)
• h2_color: H2 color, subtitle in login page (default: #0f1015)
• navbar_text_color: Navigation bar links and text color (default: #1c1d26)
• navbar_hover_color: Hover color for navigation bar links (default: #00a3b0)
• display_version: Display the JupyterHub version in the footer (default: False)
• keycloak_realm_name: Keycloak realm name (default: "nebari")

Note The default colors, typefaces and logos are chosen based on the Nebari branding. You can find more about this on the Nebari design repository.

:computer: You can see an example of these variables and the configuration in test_jupyterhub_config.py.

Nebari internal options:

• cdsdashboards_enabled: This requires cdsdashboards to be present in the JupyterHub environment (default: False)
• cdsdashboards_restricted: This requires cdsdashboards to be present in the JupyterHub environment (default: False)
• nebari_theme_extra_js_urls

Architecture 🏗

This repository is structured as follows:

• .github: GitHub Actions configuration files and repository templates
• images: Images used in this README
• nebari_jupyterhub_theme: Python package containing the jinja2 templates and static files
• pyproject.toml: Python project configuration file
• test_jupyterhub_config.py: Example JupyterHub configuration file - used by hatch run dev:render to start a local JupyterHub instance for local development.
• RELEASE.md: Release process documentation
• .pre-commit-config.yaml: Configuration file for the pre-commit tool (note we use pre-commit CI to automatically run pre-commit on all PRs and update the hooks)

Contributing to nebari-nebari_jupyterhub_theme👩‍💻

Thinking about contributing? Check out our Contribution Guidelines to get started.

Code of Conduct 📖

To guarantee a welcoming and friendly community, we require all community members to follow our Code of Conduct.

License 📄

nebari-nebari_jupyterhub_theme is licensed under the BSD-3 OSI licenses.