This repository provides a minimal, reproducible Python 3.11 environment using pyproject.toml, a Makefile, and Docker. It's designed for running a Jupyter Notebook server either locally in a virtual environment or within an isolated, consistent container.

• Two Workflows: Choose between a local virtual environment (.venv) or a fully containerized Docker setup.
• Modern Packaging: Dependencies are managed declaratively with pyproject.toml.
• Automation: A powerful Makefile simplifies installation, development, testing, and container management.
• Cross-Platform: Instructions are provided for a seamless experience on macOS, Linux, and Windows.

You have two main options. Choose the one that best fits your workflow.

1. For Local Development:

   • Python 3.11
   • GNU Make (make or gmake)
   • A POSIX shell like bash (Git Bash is recommended on Windows).

2. For Docker (Recommended):

   • Docker Desktop (macOS, Windows) or Docker Engine (Linux).
   • GNU Make (optional, but recommended for using the Makefile shortcuts).

See the OS-Specific Setup section at the bottom for detailed installation instructions.

Using Docker is the easiest way to get started. It requires no local Python installation and guarantees a perfectly consistent environment across any machine.

1. Build the Docker Image This command packages the Python environment and all dependencies into a self-contained image named simple-env:latest.

   make build-container

2. Run the Jupyter Container This starts the container, maps port 8888 to your machine, and mounts the current project directory into the container's /workspace folder.

   make run-container

3. Access Jupyter Notebook Open your browser and navigate to the URL provided in the terminal output: 🔗 http://localhost:8888

   Any notebooks you create or modify will be saved directly in your local project folder because it's mounted into the container.

The Makefile provides several commands to manage the container's lifecycle:

• make build-container: Build or rebuild the Docker image.
• make run-container: Start the container in the background.
• make logs: View live logs from the Jupyter server (press Ctrl-C to exit).
• make stop-container: Stop the container without removing it.
• make remove-container: Stop and permanently remove the container.

Use this method if you prefer to manage a Python virtual environment directly on your host machine.

1. Create Virtual Environment & Install Dependencies This command creates a .venv folder and installs the packages defined in pyproject.toml.

   make install

   Note: On macOS with Homebrew, you may need to use gmake install. On Windows with Git Bash, use make install PYTHON="py -3.11".

2. Activate Environment & Launch Jupyter

   # Activate on macOS/Linux
   source .venv/bin/activate
   
   # Activate on Windows (Git Bash)
   source .venv/Scripts/activate
   
   # Launch the notebook server
   jupyter notebook

• make dev: Install in editable mode with development dependencies.
• make update: Upgrade all project dependencies to their latest versions.
• make shell: Open a new shell with the virtual environment already activated.
• make clean: Remove build artifacts and the .venv directory.

Docker Hub

docker pull docker.io/ruslanmv/simple-environment:latest

GHCR

docker pull ghcr.io/ruslanmv/simple-environment:latest

Docker Hub

docker pull docker.io/ruslanmv/simple-environment:uv

GHCR

docker pull ghcr.io/ruslanmv/simple-environment:uv

# Map host port 8888 -> container 8888 and mount current dir into /work (optional)
docker run --rm -it -p 8888:8888 -v "$PWD":/work   docker.io/ruslanmv/simple-environment:v0.1.0
# then open http://localhost:8888

docker run --rm docker.io/ruslanmv/simple-environment:v0.1.0 python --version
docker run --rm docker.io/ruslanmv/simple-environment:v0.1.0 jupyter --version

To add new libraries like pandas or matplotlib, follow this process to ensure your environment remains reproducible.

1. Update pyproject.toml: Add the new package names to the dependencies list.

   # pyproject.toml
   [project]
   # ... other settings
   dependencies = [
     "notebook",
     "ipykernel",
     "pandas",         # <-- Add new package here
     "matplotlib"      # <-- And here
   ]

2. Rebuild Your Environment:

   • Docker: You must rebuild the image to include the new libraries.

     make build-container

   • Local: Simply run the installation command again. It will add the new packages to your .venv.

     make install

Your data is safe. When you run make run-container, the command uses a bind mount (-v "$(pwd)":/workspace) to link your local project folder to the /workspace directory inside the container.

• Analogy: Think of the container as a temporary office and the bind mount as a magic portal on your desk. Anything you create or modify in the /workspace directory (through the portal) is instantly saved in your project folder on your actual computer.
• What is lost?: Any files created outside of the /workspace directory will be destroyed when you run make remove-container.
• Bottom Line: Always save your work inside the /workspace folder.

You can run commands directly without starting the Jupyter server. This is useful for running scripts or accessing a shell.

• Run a Python script: The --rm flag automatically removes the container after the script finishes.

  docker run --rm -v "$(pwd)":/workspace simple-env:latest python your_script.py

• Get an interactive shell inside the container: This is great for debugging or running ad-hoc commands.

  docker run --rm -it -v "$(pwd)":/workspace simple-env:latest bash

[build-system]
requires = ["setuptools>=64", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "simple-environment"
version = "0.1.0"
description = "Minimal environment for Jupyter Notebook (Python 3.11)."
requires-python = ">=3.11,<3.12"
dependencies = [
  "notebook",
  "ipykernel"
]

# syntax=docker/dockerfile:1
FROM python:3.11-slim

# Prevent Python from writing .pyc files and buffer stdout
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1

# Install system dependencies required for building some Python packages
RUN apt-get update && apt-get install -y --no-install-recommends build-essential && \
    rm -rf /var/lib/apt/lists/*

# Set the working directory for the application code
WORKDIR /opt/app

# Copy project files and install dependencies
COPY . .
RUN python -m pip install --upgrade pip && \
    pip install .

# Set the final working directory for user data and expose the port
WORKDIR /workspace
EXPOSE 8888

# Command to run Jupyter Notebook
CMD ["jupyter", "notebook", "--ip=0.0.0.0", "--no-browser", "--allow-root", "--NotebookApp.token="]

sudo apt update
sudo apt install -y make python3.11 python3.11-venv
make --version
python3.11 --version

# Install Git (which includes Git Bash)
winget install -e --id Git.Git

# Install Python 3.11
winget install -e --id Python.Python.3.11

# 1. Allow local scripts to run
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force

# 2. Install Scoop
irm get.scoop.sh | iex

# 3. Use Scoop to install Make
scoop install make

# You can also install Git and Python with Scoop
scoop install git
scoop bucket add versions
scoop install python311

# 1. Allow scripts, set security protocol, and install Chocolatey
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iwr https://community.chocolatey.org/install.ps1 -UseBasicParsing | iex

# 2. Use Chocolatey to install Make
choco install make -y

# You can also install Git and Python with Chocolatey
choco install git -y
choco install python --version=3.11.9 -y

# Use Winget to install Make
winget install -e --id GnuWin32.Make

# Check versions to confirm installation was successful
git --version
py -3.11 -V
make --version

• make: command not found: Install GNU Make using the OS-specific instructions. On macOS, remember to use gmake or create an alias.
• Jupyter can’t see the kernel (local setup): Ensure you've activated the virtual environment (source .venv/bin/activate) before running jupyter notebook.
• Permission Denied (Docker on Linux): You may need to run Docker commands with sudo or add your user to the docker group.

• Local Environment:

  make clean

• Docker Environment:

  make remove-container