🤖 MaxLab - JupyterLab Environment

MaxLab is a Python data science environment based on JupyterLab

Features:

• 📓 Pre-configured JupyterLab - Ready-to-use data science environment with pandas, numpy, matplotlib, and more
• 🐳 Docker-based - Consistent environment across all platforms
• 🎨 Custom MaxLab Themes - Includes NavigatorBBS-inspired light and dark JupyterLab themes plus MaxLab sidebar branding
• 🧹 Automatic Output Cleaning - Pre-commit hooks keep your repository clean
• 🔧 Easy Publishing - Built-in scripts to push images to Docker Hub

---

🚀 Quick Start

Start MaxLab with Docker Compose

# Build and run
docker compose up

# Run in background
docker compose up -d

# Stop
docker compose down

JupyterLab will be available at http://localhost:8888

Using PowerShell Scripts

# Build the image
./scripts/docker-build.ps1

# Run with docker compose
./scripts/docker-run.ps1

---

⚙️ Configuration

Environment Variables

Copy .env.example to .env and customize:

Copy-Item .env.example .env

Edit .env for your setup:

JUPYTER_PORT=8888                  # Port to expose JupyterLab
JUPYTER_NOTEBOOK_DIR=workspace     # Notebooks directory
DATA_DIR=workspace/data            # Data directory
API_KEY=your_api_key_here          # Example secret
GITHUB_COPILOT_PAT=your_github_copilot_pat_here  # Copilot token for sysop chat extension

Load variables in a notebook:

from dotenv import load_dotenv
load_dotenv()

Docker Configuration

The container respects these environment variables (set in .env or docker-compose.yml):

Variable	Default	Description
JUPYTER_PORT	8888	Port to expose JupyterLab
GITHUB_COPILOT_PAT	(empty)	GitHub Copilot token used by the sysop Copilot AI chat notebook extension
DOCKERHUB_USERNAME	local	Docker namespace/user
DOCKER_REPOSITORY	maxlab	Docker repository name
DOCKER_TAG	latest	Docker image tag

Sysop Copilot AI Chat Extension

To use the sysop Copilot AI chat agent Jupyter notebook extension:

1. Add your token to .env:

   GITHUB_COPILOT_PAT=your_github_copilot_pat_here

2. Start or restart the container so the new environment variable is loaded:

   docker compose up --build -d

3. Open JupyterLab and run the sysop notebook extension. It reads GITHUB_COPILOT_PAT from the container environment.

For more details on usage, see the sysop project: https://github.com/NavigatorBBS/sysop

Security note: keep .env local and never commit real tokens.

---

🎨 MaxLab JupyterLab Themes

The Docker image now includes two MaxLab themes implemented as bundled JupyterLab extensions:

• MaxLab Navigator Dark
• MaxLab Navigator Light

Both themes keep native JupyterLab layout and behavior while applying a NavigatorBBS-inspired palette with subtle teal/green accents.

The image also includes a small branding extension that places maxlab_logo.png above the file browser launcher controls in the left sidebar.

MaxLab starts with MaxLab Navigator Dark by default on first launch.

Switching Themes

1. Start MaxLab with Docker Compose.
2. Open JupyterLab.
3. Go to Settings -> Theme.
4. Choose MaxLab Navigator Dark or MaxLab Navigator Light.

Theme Package Source

The bundled Python package lives at packages/maxlab_navigator_theme.

Frontend sources are split into three JupyterLab prebuilt extensions:

• js/maxlab-navigator-dark
• js/maxlab-navigator-light
• js/maxlab-branding

To rebuild the extension assets locally:

npm install --prefix .\packages\maxlab_navigator_theme\js\maxlab-navigator-light
npm install --prefix .\packages\maxlab_navigator_theme\js\maxlab-navigator-dark
npm install --prefix .\packages\maxlab_navigator_theme\js\maxlab-branding

npm run build:prod --prefix .\packages\maxlab_navigator_theme\js\maxlab-navigator-light
npm run build:prod --prefix .\packages\maxlab_navigator_theme\js\maxlab-navigator-dark
npm run build:prod --prefix .\packages\maxlab_navigator_theme\js\maxlab-branding

To rebuild the Python distribution:

python -m build .\packages\maxlab_navigator_theme

---

🐳 Docker Hub Publishing

Configure Docker Hub Credentials

Add to .env:

DOCKERHUB_USERNAME=your-username
DOCKERHUB_TOKEN=your-access-token
DOCKER_REPOSITORY=maxlab
DOCKER_TAG=dev

Push Image to Docker Hub

./scripts/docker-push.ps1

This builds and pushes both latest and your custom DOCKER_TAG.

CI/CD Publishing

The GitHub Actions workflow automatically builds and pushes to Docker Hub when you push a Git tag:

git tag v1.0.0
git push origin v1.0.0

Configure these secrets in your GitHub repository:

• DOCKERHUB_USERNAME
• DOCKERHUB_TOKEN

---

📦 Runtime Package Installation

The Docker image already includes sysop in the maxlab conda environment (installed at build time from git+https://github.com/NavigatorBBS/sysop.git@v0.1.0).

Install packages at runtime within a notebook:

%pip install package-name

---