Prerequisites

Before setting up Micronaut Jupyter, ensure you have the following installed:

Jupyter Environment

Install Jupyter with the tested configuration:

pip install ipykernel==6.29.5 notebook==6.5.7 tornado==6.4.1 jupyter-client==7.4.9 jupyterlab==3.5.3

While later versions may work, this specific combination has been thoroughly tested.

BeakerX Dependencies (Optional but Recommended)

For enhanced visualization and BeakerX features, you’ll need to build BeakerX 2.0 manually since it’s not yet published:

git clone --recurse-submodules https://github.com/stainlessai/beakerx-jlab2

cd beakerx-jlab2/beakerx_kernel_base
./gradlew install -xtest

cd ../beakerx_kernel_groovy
./gradlew install -xtest

This builds the required BeakerX 2.0-SNAPSHOT jars to your local Maven cache.

Project Setup

Add Build Dependencies

Add the necessary repositories to your build.gradle:

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
    mavenLocal() // Required if using BeakerX 2.0-SNAPSHOT
}

Add the Micronaut Jupyter dependency:

dependencies {
    implementation "ai.stainless:micronaut-jupyter:1.1.2"
}

Configure Kernel Installation Directory

Micronaut Jupyter needs to install kernel specifications that Jupyter can find. Choose one of these approaches:

Option 1: Default System Directory (Development Only)

This approach has security implications and should only be used in development environments.

Make the default Jupyter kernels directory writable:

sudo chmod 777 /usr/local/share/jupyter/kernels

Option 2: Custom Directory (Recommended)

Create a dedicated directory for kernels:

sudo mkdir -p /opt/jupyter-kernels
sudo chown $USER:$USER /opt/jupyter-kernels

Configure Jupyter to search this directory by setting the JUPYTER_PATH environment variable:

export JUPYTER_PATH="/opt/jupyter-kernels:$JUPYTER_PATH"

Add this to your shell profile (.bashrc, .zshrc, etc.) to make it permanent.

Configure your Micronaut application to use this directory in application.yml:

jupyter:
  kernel:
    location: /opt/jupyter-kernels/kernels

Option 3: User Directory

Use Jupyter’s user-specific directory (no special permissions required):

mkdir -p ~/.local/share/jupyter/kernels

Configure your application:

jupyter:
  kernel:
    location: ~/.local/share/jupyter/kernels

Application Configuration

Basic Configuration

Add basic Micronaut Jupyter configuration to your application.yml:

jupyter:
  kernel:
    # Kernel installation directory (see options above)
    location: /opt/jupyter-kernels/kernels
    # Redirect kernel output to application logs
    redirectLogOutput: true
    # Kernel shutdown timeout
    shutdownTimeoutMs: 5000

Advanced Configuration Options

jupyter:
  kernel:
    location: /opt/jupyter-kernels/kernels
    redirectLogOutput: true
    shutdownTimeoutMs: 10000
    # Additional JVM options for kernel processes
    jvmOpts: "-Xmx512m -XX:+UseG1GC"

Docker Support

Each example includes a Dockerfile for containerized deployment. To run with Docker:

# Build the image
docker build -t my-micronaut-jupyter .

# Run with Jupyter accessible
docker run -p 8888:8888 -p 8080:8080 my-micronaut-jupyter

The container exposes: - Port 8080: Your Micronaut application - Port 8888: Jupyter Lab interface