Merge pull request #7 from OpenTechIL/develop

Develop

Author: alefbt

AGENTS.md

@@ -77,5 +77,5 @@ The project adheres to the `git-flow` branching model:
 ### 2.4. General Project Conventions
 
 *   **Documentation**: Ensure `README.md` and `CONTRIBUTORS.md` are kept up-to-date.
-*   **Dependency Management**: Python dependencies are managed via `requirements.txt`. Any additions should be made there and trigger a Docker image rebuild.
+*   **Dependency Management**: Python dependencies are managed via runtime image wheelhouse. Core packages are provided by the base runtime image (`ghcr.io/opentechil/offline-python-runtime-docker:v1.1.0-release.0`), while additional packages can be installed at runtime or via project-specific `requirements.txt` for persistent installations.
 *   **Offline Focus**: All configurations and scripts should prioritize and support the offline/air-gapped nature of the development environment.

CHANGELOG.md

@@ -0,0 +1,100 @@
+# 📝 Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.1] - 2026-01-07
+
+### 🚀 Updates
+- **Runtime Image Update**: Updated to `ghcr.io/opentechil/offline-python-runtime-docker:v1.1.0-release.0`
+- **Documentation Enhancement**: Added clear guidance on offline package management process
+- **Repository Links**: Added direct links to runtime image repository for package requests
+
+### 📦 Package Management
+- **Offline Package Process**: Documented process for adding packages to offline environments via runtime image
+- **Repository Integration**: Enhanced documentation linking to [runtime image repository](https://github.com/OpenTechIL/offline-python-runtime-docker)
+
+---
+
+## [1.1.0] - 2026-01-07
+
+### 🚀 Major Changes
+- **Runtime Image Integration**: Now uses `ghcr.io/opentechil/offline-python-runtime-docker:v1.0.0-release.0` as base image
+- **Runtime Package Management**: Wheelhouse and package management moved to runtime for better compatibility
+
+### ✨ New Features
+- **Oracle Driver Support**: Leverages Oracle Instant Client from runtime image
+- **Runtime Wheelhouse**: Package installation handled at runtime through pre-configured wheelhouse system
+- **Simplified Architecture**: Removed local `requirements.txt` dependencies, now managed by runtime image
+
+### 🔄 Changes
+- **Package Management**: Core packages (pandas, oracledb, cryptography, etc.) now provided by runtime image
+- **Build Process**: Streamlined build process leveraging runtime image foundation
+- **Compatibility**: Enhanced offline compatibility through runtime wheelhouse system
+- **Runtime Repository**: Integration with [offline-python-runtime-docker](https://github.com/OpenTechIL/offline-python-runtime-docker) repository
+
+### 📦 Package Updates
+- Core Python packages now sourced from runtime image
+- Oracle Instant Client 19.29 included via runtime image
+- Data science stack (pandas, numpy, scikit-learn) available from runtime
+
+### 🏗️ Architecture
+- **Multi-stage build**: Runtime image as foundation with devcontainer customization
+- **Optimized layers**: Better Docker layer caching and reduced build times
+- **Runtime flexibility**: Package installation available both at build time and runtime
+
+### 📚 Documentation
+- Updated README.md to reflect runtime image usage
+- Added runtime architecture explanations
+- Updated configuration examples for runtime package management
+
+---
+
+## [1.0.x] - Previous Versions
+
+### 🐛 Known Issues
+- Package management complexity with local wheelhouse
+- Build image size optimization needed
+- Oracle driver compatibility issues in some environments
+
+---
+
+## Migration Guide
+
+### From v1.0.x to v1.1.0
+
+**Breaking Changes**:
+- Local `requirements.txt` packages are no longer built into the image
+- Package management now happens at runtime
+
+**Recommended Actions**:
+1. Update your development workflow to install packages at runtime:
+   ```bash
+   # Inside devcontainer
+   pip install your-package
+   ```
+
+2. For persistent packages, create project-specific `requirements.txt` and install when container starts
+
+3. Update build scripts to use the new runtime image base
+
+**Benefits**:
+- Faster build times
+- Better package compatibility
+- Simplified maintenance
+- Access to runtime wheelhouse with pre-compiled packages
+
+---
+
+## Version Support
+
+| Version | Status | Support End |
+|---------|--------|-------------|
+| 1.1.x   | ✅ Current | TBD |
+| 1.0.x   | ⚠️ Legacy | 2026-03-07 |
+
+---
+
+*For detailed release notes and migration guides, check the [GitHub Releases](https://github.com/OpenTechIL/offline-python-vscode-devcontainer/releases) page.*

Dockerfile

@@ -1,47 +1,68 @@
-####### W: 3.0.3-3.13-trixie
-FROM mcr.microsoft.com/devcontainers/python:3.13-trixie AS builder
-WORKDIR /tmp/build
-COPY requirements.txt .
+#
+# Builder image for runtime
+#   The wheelhouse located there: 
+#       https://github.com/OpenTechIL/offline-python-runtime-docker    
+#   
+#   Update exact release. not "latests" etc to be consistent
+FROM ghcr.io/opentechil/offline-python-runtime-docker:v1.1.0-release.0 AS builder
 
-ENV PIP_ROOT_USER_ACTION=ignore
 
-RUN python -m pip install --no-cache-dir --upgrade pip
-RUN pip install --no-cache-dir \
-                --target=/install -r requirements.txt
-
-
-#######
+#
+# Actual docker for 
+#
 FROM mcr.microsoft.com/devcontainers/python:3.13-trixie
 
-COPY --from=builder /install /usr/local/lib/python3.13/site-packages
-
+##
+## ORACLE
+##
 RUN apt-get update && apt-get install -y libaio1t64 libaio-dev unzip curl python3-venv && rm -rf /var/lib/apt/lists/*
 
-WORKDIR /opt/oracle
-
-RUN curl -o instantclient-basic.zip https://download.oracle.com/otn_software/linux/instantclient/1929000/instantclient-basic-linux.x64-19.29.0.0.0dbru.zip && \
-    unzip -o instantclient-basic.zip && \
-    rm instantclient-basic.zip
-
-RUN ln -s /usr/lib/x86_64-linux-gnu/libaio.so.1t64 /usr/lib/x86_64-linux-gnu/libaio.so.1
+COPY --from=builder /opt/oracle/instantclient_19_29 \
+                    /opt/oracle/instantclient_19_29
 
 ENV LD_LIBRARY_PATH=/opt/oracle/instantclient_19_29:$LD_LIBRARY_PATH
 ENV ORACLE_HOME=/opt/oracle/instantclient_19_29
 ENV ORACLE_INSTANTCLIENT_PATH=/opt/oracle/instantclient_19_29
 
+RUN ln -s /usr/lib/x86_64-linux-gnu/libaio.so.1t64 /usr/lib/x86_64-linux-gnu/libaio.so.1
+
+
+
+##
+## PYTHON and wheelhouse
+##
+COPY --from=builder /lib/python_wheelhouse \
+                    /lib/python_wheelhouse
+
+COPY --from=builder /usr/local/lib/python3.13/site-packages \
+                    /usr/local/lib/python3.13/site-packages
+
+COPY --from=builder /etc/pip.conf \
+                    /etc/pip.conf
+
+# python testing
 COPY --chown=vscode:vscode ./py-apps/ /home/vscode/py-apps/
-RUN su vscode -c "pytest -v /home/vscode/py-apps/tests/"
+RUN su vscode -c "cd /home/vscode/py-apps/ && \
+chmod +x ./run-tests.sh && \
+./run-tests.sh"
+
 
+##
+##  VS Code configurations
+##
 # Ensure VS Code server directories exist with correct permissions
 RUN mkdir -p /home/vscode/.vscode-server/extensions && \
     mkdir -p /home/vscode/.vscode-server/data && \
     chown -R vscode:vscode /home/vscode/.vscode-server
 
-    
+
+##
+##  Cleanups
+##
 # Clean up temporary extension files but keep installed extensions
-RUN rm -rf /tmp/extensions && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+RUN apt-get clean && \
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \
+    rm -rf /tmp/extensions
 
 
 # Set a reasonable workdir for VS Code

README.md

@@ -19,6 +19,7 @@
 - [💻 Usage](#-usage)
 - [⚙️ Configuration](#️-configuration)
 - [🔒 Security](#-security)
+- [📝 Changelog](#-changelog)
 - [🐛 Troubleshooting](#-bug-troubleshooting)
 - [🤝 Contributing](#-contributing)
 - [📄 License](#-license)
@@ -27,11 +28,12 @@
 
 - 🌐 **Offline-First**: Complete air-gapped development environment
 - 🐳 **Container-Based**: Isolated development with Podman/Docker support
-- 🐍 **Python 3.13**: Latest Python version with pre-installed packages
-- 🗄️ **Oracle Database**: Built-in Oracle Instant Client support
+- 🐍 **Python 3.13**: Latest Python version with runtime image foundation
+- 🗄️ **Oracle Database**: Built-in Oracle Instant Client from runtime image
 - 📝 **VSCode Integration**: Seamless development experience
 - 🧪 **Testing Ready**: Pre-configured pytest environment
-- 📦 **Pre-installed Packages**: pandas, cryptography, oracledb, pytest, ipykernel
+- 🏗️ **Runtime Image Base**: Built on `ghcr.io/opentechil/offline-python-runtime-docker:v1.1.0-release.0`
+- 📦 **Runtime Wheelhouse**: Package management handled at runtime for compatibility
 - 🔧 **Customizable**: Easy to extend with additional packages
 - 🛡️ **Security-Focused**: Non-root user execution
 
@@ -161,6 +163,7 @@ import oracledb
 print("🐍 Python environment ready!")
 print(f"📊 Pandas version: {pd.__version__}")
 print(f"🗄️ Oracle DB available: {oracledb.__version__}")
+print(f"🏗️ Runtime image foundation active")
 EOF
 
 # Run with mounted volume
@@ -187,23 +190,49 @@ podman run \
 
 ## ⚙️ Configuration
 
+### Runtime Image Architecture
+This devcontainer is built on top of the offline Python runtime image which provides:
+- **Oracle Instant Client**: Full database connectivity support
+- **Core Packages**: Essential Python packages pre-installed
+- **Runtime Wheelhouse**: Package management handled at runtime for compatibility
+
+**📦 Runtime Image Repository**: [github.com/OpenTechIL/offline-python-runtime-docker](https://github.com/OpenTechIL/offline-python-runtime-docker) - The base runtime image provides the core Python environment, Oracle drivers, and offline package management capabilities.
+
 ### Adding Python Packages
-1. Edit `requirements.txt`:
+Since v1.1.0, package management is handled at runtime through the wheelhouse system:
+
+1. **For container runtime**: Install packages directly in the running container:
+   ```bash
+   # Inside the devcontainer
+   pip install numpy matplotlib seaborn
+   ```
+
+2. **For persistent packages**: Add to your project's `requirements.txt`:
    ```
-   pandas
-   cryptography
-   oracledb
-   pytest
-   ipykernel
-   # Add your packages here
    numpy
    matplotlib
+   seaborn
+   # Your application-specific packages
    ```
 
-2. Rebuild the image:
-   ```bash
-   podman build . -t offline-python-vscode-devcontainer:dev-latest-local
-   ```
+3. **Runtime wheelhouse access**: All packages are installed from the pre-configured wheelhouse for offline compatibility.
+
+Note: Core packages (pandas, cryptography, oracledb, pytest, ipykernel) are provided by the base runtime image and available immediately.
+
+### 📦 Adding Packages to Offline Environment
+
+**⚠️ Important**: For packages to be available in offline environments, they must be added to the **runtime image** itself:
+
+- **Runtime Image Repository**: [github.com/OpenTechIL/offline-python-runtime-docker](https://github.com/OpenTechIL/offline-python-runtime-docker)
+- **How to Add**: Submit a PR or issue to the runtime image repository with your package requirements
+- **Why**: The runtime image contains the pre-built wheelhouse that enables offline package installation
+
+**Process for Adding New Offline Packages**:
+1. Check if the package already exists in the runtime image
+2. If not, open an issue or PR in the [runtime image repository](https://github.com/OpenTechIL/offline-python-runtime-docker)
+3. Once included in a new runtime release, update this devcontainer to use the new version
+
+This ensures your packages are available for true offline deployment without requiring network access.
 
 ### Custom VSCode Extensions
 Update `.devcontainer/devcontainer.json`:
@@ -250,6 +279,10 @@ podman run -v ./project:/home/vscode/project:Z \
 - 🔒 **No network access**: Container runs in isolation
 - 📋 **Minimal attack surface**: Only essential packages installed
 
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history and feature updates.
+
 ## 🐛 Troubleshooting
 
 ### Common Issues

docs/updates/260107 2018 - use runtime image.md

@@ -0,0 +1,8 @@
+Data: 07.01.2026
+
+Will use `ghcr.io/opentechil/offline-python-runtime-docker:v1.0.0-release.0`
+as build image to take the packages, and oracle driver
+
+Removed `requirements.txt` all packages and wheelhouse will be managed at runtime for compatibility 
+in https://github.com/OpenTechIL/offline-python-runtime-docker
+

py-apps/requirements.txt

@@ -0,0 +1,6 @@
+# The disterbutions should be exists as whl
+# from runner docker in Wheelhouse:
+#   https://github.com/OpenTechIL/offline-python-runtime-docker
+#
+oracledb
+pytest

py-apps/run-tests.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+set -e 
+
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+pytest -v /home/vscode/py-apps/tests/
+
+.venv/bin/deativate
+
+rm -rf .venv