Skip to content

nebari-dev/nebari-jupyterhub-theme

Β 
Β 

Nebari logo mark - text will be black in light color mode and white in dark color mode.

Information Links
Project License Nebari documentation PyPI package version
Community GH discussions Open an issue Nebari documentation - Community guidelines

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.

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.

    Login page of a local JupyterHub instance with the Nebari JupyterHub theme - the main text reads "welcome to Nebari your open source data science platform". The subheading reads "Running in dev mode". In the middle of the page there is the JupyterHub authentication form with a "username" and "password" fields.

    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.

πŸ’» 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.

Packages

No packages published

Languages

  • CSS 60.8%
  • HTML 25.7%
  • Python 11.9%
  • Nix 1.4%
  • Shell 0.2%