Jupyter + OpenAI + Docker Dev Stack

This project sets up a reproducible development environment for OpenAI-based agents programmed via Jupyter Notebook. It can be run in two ways - via Docker or via Skaffold + Minikube.

Features

• Full local development loop with Jupyter + OpenAI
• Notebook data stored locally and mounted into Docker or Kubernetes
• Secrets sourced securely from ~/.ssh/openai_api_key.txt
• Easily extensible with LangChain, LangGraph, and your own agents

Tech Stack

• Docker to containerize Jupyter Lab
• Minikube for local Kubernetes clusters
• PersistentVolumes to retain notebook data
• Secrets to securely pass the OpenAI API key
• Skaffold to manage build and deploy workflows
• Makefile to automate everything

Project Structure

my-agent-project/
├── Dockerfile                  # Builds Jupyter agent container
├── Makefile                    # Automates builds, mounts, and deploys
├── requirements.txt            # Python deps (openai, jupyter, etc.)
├── notebooks/                  # Local notebook files (mounted into pod)
├── k8s/
│   ├── deployment.yaml         # Jupyter deployment
│   ├── service.yaml            # NodePort service (8899)
│   └── pv-pvc.yaml             # PersistentVolume + PersistentVolumeClaim
└── skaffold.yaml               # Skaffold config for build + deploy

Dev Workflow

• Jupyter runs from /app/notebooks, which maps to your local ./notebooks
• OpenAI key is passed into the container as the OPENAI_API_KEY env var
• OpenAI API key stored at: ~/.ssh/openai_api_key.txt

Docker Only

Prerequisites

• Docker

Commands

make docker-build # builds the docker image
make docker-run   # runs the docker container for Jupyter Notebook

Skaffold + Minikube

Skaffold will monitor the Dockerfile and other Kubectl yaml files for changes. If any of them change, skaffold will handle the redeploy for you on the fly. If you are unfamiliar, I recommend taking a look: Skaffold. This strategy configures the minikube cluster with the mount and the OpenAI API Key secret and then uses Skaffold to build and deploy.

Prerequisites

• Docker
• Skaffold (v2.16.0 or higher)
• Minikube

Single Command

make dev # aggregate of all minikube and skaffold commands

Detailed Commands

make minikube-start   # starts Minikube
make minikube-mount   # mounts the ./notebook directory in the repo
make minikube-storage # creates PV and PVC for the mounted directory
make minikube-secret  # creates the secret at `~/.ssh/openai_api_key.txt` as a secret in minikube
make skaffold-dev     # Builds docker image and deploys to minikube cluster

Jupyter Notebook Access

Access Jupyter Lab at: http://localhost:8899

Cleanup

Deletes the Docker image and the minikube cluster but does not touch your notebooks since those were a mounted volume.

make clean

Next Steps

• add troubleshooting section
• add skaffold debug