micronaut-jupyter
A Micronaut configuration that integrates your app with an existing Jupyter installation.
Features
Micronaut kernel
A special Micronaut kernel is provided to Jupyter that can be used to run notebooks. This kernel can:
- Execute Groovy code
- Import classes on your Micronaut app's classpath
- Access Micronaut beans
- Use Micronaut Data repositories
- Use GORM Data Services and dynamic finders
- Access functionality available to the
BeakerX Groovy
kernel
- Note: This requires that the
beakerx
Python package (and possibly other Jupyter packages) be installed on the system separately.
- Note: This requires that the
Setup
Micronaut 2 Compatibility
The micronaut2
branch of this repository has been updated to support Micronaut 2.0+, however, it requires BeakerX 2.0
libraries which have not yet been published by the BeakerX project team at the time of this writing. To build the required
libraries locally, follow these steps:
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
The beakerx-*-2.0-SNAPSHOT jars should now be in your local maven cache, e.g.:
~/.m2/repository/com/twosigma/beakerx-kernel-base/2.0-SNAPSHOT/beakerx-kernel-base-2.0-SNAPSHOT.jar
Building
Build the library and publish to local maven:
./gradlew publishToMavenLocal
To set a specific version on your library:
./gradlew publishToMavenLocal -PprojectVersion=0.0.1-mysemanticversion
Usage
Add Build Dependency (Gradle)
Ensure the following repositories are added to your gradle build:
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
Add the following dependency to your gradle build:
dependencies {
implementation "ai.stainless:micronaut-jupyter:0.2.4"
}
Configure your Jupyter Kernels Directory
Ensure that your app can write to a directory where Jupyter will search for kernels.
Option 1 - Easiest (Possible security vulnerability!)
The default directory is /usr/local/share/jupyter/kernels
, so the following
is sufficient:
chmod 777 /usr/local/share/jupyter/kernels
Option 2 - May be More Secure
Create a separate directory, say at /opt/jupyter-alt/kernels
, that your app
can write to. Then, configure Jupyter to search this directory using
JUPYTER_PATH.
Lastly, add the following config to your application.yml:
jupyter:
kernel:
location: /opt/jupyter-alt/kernels
Usage
When your app starts up, this configuration will make any necessary configurations to Jupyter. Once both your app and Jupyter are running, login to Jupyter to start using the features.
See the /examples directory for example apps that use this configuration along with sample Jupyter notebooks that take advantage of the available features.
Development
Branches
The master
branch contains the latest production release. The develop
branch contains
the latest stable build. It is recommended that most PRs be submitted
to the develop
branch in order to ensure that they are based on the most
recent version of the code. Most PRs that are submitted to master
will be
rebased onto develop
. Exceptions to this would include things like critical
bugfixes that need to be pushed ahead of the next planned release.
Testing
Docker Required
In order to run the tests, you must have Docker installed on your dev environment. The tests use a library called Testcontainers, so you'll need to meet its system requirements (see link) in order to run the tests. The tests run in Travis CI out of the box; on a local machine, installing Docker Desktop should be sufficient.
Running the Tests
Run all the tests:
./gradlew test
Run integration and unit tests separately
./gradlew integrationTest
./gradlew unitTest
Gradle's --tests
option won't apply to subtasks, so use -Ptests
to filter
the tests:
./gradlew test -Ptests=*BasicGroovy*
./gradlew integrationTest -Ptests=*Finder*
Planned Features
- Import classes on app classpath in Jupyter script
- Access GORM methods in Jupyter scripts
- Access beans in Jupyter script
- Ability to add custom methods and properties to scope of Jupyter script
- Access GORM Data Services from Jupyter script
- Access Micronaut Data repositories from Jupyter script