jovykit 3.0.0

Layered Jupyter container images and project-local JovyKit environments.

JovyKit

JovyKit provides layered Jupyter notebook container images for data science, machine learning, and research workflows.

The images are designed as progressively larger environments, so users can pick the smallest image that fits their workload:

• minimal: Jupyter runtime plus the core scientific Python stack.
• base: everyday data science, classical machine learning, statistics, and local data access.
• extended: advanced machine learning, NLP, time series, distributed compute, and API tooling.
• full: heavy frameworks, generative AI tooling, graph and geospatial analysis, big data, and additional research utilities.

Images

Published image variants use the following naming pattern:

ghcr.io/mihneateodorstoica/jovykit-TYPE:latest
ghcr.io/mihneateodorstoica/jovykit-TYPE:nightly
ghcr.io/mihneateodorstoica/jovykit-TYPE:lts

TYPE is one of minimal, base, extended, or full.

All image variations include client-side SSH tooling for Git remotes, file copying, and SSH-backed sync:

• ssh, scp, and sftp from OpenSSH
• git
• rsync

Build Locally

Build a specific image target from the repository root:

docker build --target minimal -t jovykit-minimal ./image
docker build --target base -t jovykit-base ./image
docker build --target extended -t jovykit-extended ./image
docker build --target full -t jovykit-full ./image

CLI

JovyKit includes a CLI for project-local container environments. The mental model is:

.jovy is to JovyKit what .venv is to Python.

Create an environment, add project packages, and run Jupyter:

jovy init .jovy --image base --gpus auto
jovy add pandas scikit-learn plotly
jovy install
jovy run

Run jovy with no subcommand to open the interactive terminal dashboard for the current project. The dashboard shows environment status, recent logs, and a jovy> command line for common operations. Closing the dashboard with quit or exit does not stop the container; use jovy down or down inside the dashboard when you want to stop it.

The CLI creates a local work/ directory for project files and writes a root jovy.toml plus a reproducible overlay build recipe under .jovy/:

jovy.toml
work/
.jovy/
  jovy.lock
  Containerfile
  compose.yaml
  state.json

Useful commands:

jovy --version
jovy
jovy status
jovy status --json
jovy remove plotly
jovy add -r requirements.txt
jovy install
jovy install --upgrade
jovy up --no-build
jovy down --timeout 10
jovy restart
jovy build --pull
jovy run --watch
jovy logs --tail 100 --since 10m --timestamps --no-follow
jovy shell -c "python --version"
jovy exec python --version
jovy clean
jovy destroy --keep-image

Most commands accept --env PATH when you want to operate on a JovyKit environment outside the current project tree. jovy init also supports customizing the generated project name, overlay image name/tag, Jupyter port, GPU mode, Jupyter token/password/log level, and mounted work directory. The default token is empty and the default password is jovykit, so JovyKit does not rely on Jupyter's generated token. Docker Compose watch runs with jovy run; jovy up stays detached and starts a lightweight watcher that restarts the container when jovy.toml changes. Use jovy up for background startup, jovy down to stop the environment, and jovy run when you want attached foreground Jupyter logs.

jovy.toml stores direct project packages under [python].packages. JovyKit compiles them with uv into .jovy/jovy.lock, and Docker installs from that lockfile. jovy.toml can also customize runtime environment variables, extra volumes, restart policy, Jupyter command/logging, Compose Watch behavior, image build arguments, build target/platform, apt packages, and uv/pip install options.

Repository Layout

jovykit/              Python CLI package
image/               Dockerfile and layered image dependency manifests
docs/                mdBook documentation
.github/workflows/   CI, security, docs, and image publishing automation

Documentation

The mdBook source lives in docs/src.

To build the documentation locally:

mdbook build docs

Testing

Run the default deterministic test suite with coverage:

pytest --cov=jovykit --cov-report=term-missing --cov-fail-under=90

Docker-facing smoke tests are opt-in so routine CI and local test runs stay fast and deterministic:

pytest -m docker --run-docker

Contributing

Contributions are welcome. See CONTRIBUTING.md for the development workflow and CODE_OF_CONDUCT.md for community expectations.

License

This project is licensed under the MIT License. See LICENSE.