🚀 A complete offline and air-gapped Python development environment in VSCode DevContainers with pre-installed packages and Oracle DB support.

• ✨ Features
• 🎯 Why This Project
• 📋 Prerequisites
• ⚡ Quick Start
• 🔧 Installation
• 💻 Usage
• ⚙️ Configuration
• 🔒 Security
• 📝 Changelog
• 🐛 Troubleshooting
• 🤝 Contributing
• 📄 License

• 🌐 Offline-First: Complete air-gapped development environment
• 🐳 Container-Based: Isolated development with Podman/Docker 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
• 🏗️ 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

Traditional development environments require constant internet connectivity for package installation, updates, and VSCode extensions. This becomes problematic in:

• 🏢 Corporate environments with strict network policies
• 🏭 Industrial settings with air-gapped systems
• 🏝️ Remote locations with limited connectivity
• 🔒 High-security environments requiring isolation

This project provides a complete, self-contained development environment that works entirely offline, ensuring consistent development experiences across any infrastructure.

• Podman (recommended) or Docker
• VSCode with Dev Containers extension
• Git for cloning the repository

• RAM: 2GB minimum, 4GB recommended
• Storage: 5GB available space
• OS: Linux, macOS, or Windows with WSL2

💡 Note: This project uses Podman as the primary container runtime, but all commands work with Docker as well.

git clone https://github.com/OpenTechIL/offline-python-vscode-devcontainer.git
cd offline-python-vscode-devcontainer
podman build . -t offline-python-vscode-devcontainer:dev-latest-local

1. Open the project in VSCode
2. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
3. Select "Dev Containers: Reopen in Container"
4. Start coding! 🎉

git clone https://github.com/OpenTechIL/offline-python-vscode-devcontainer.git
cd offline-python-vscode-devcontainer

Press Ctrl+Shift+P and search for "Open User Settings (JSON)":

{
    "dev.containers.dockerPath": "podman",
    "dev.containers.dockerComposePath": "podman-compose",
    "dev.containers.mountWaylandSocket": false,
    "remote.downloadExtensionsLocally": true,
    "remote.autoInstallAdditionalExtensions": false,
    "dev.containers.copyGitConfig": false
}

podman build . -t offline-python-vscode-devcontainer:dev-latest-local

Create or update .devcontainer/devcontainer.json:

{
    "name": "Python Airgapped (Podman)",
    "image": "offline-python-vscode-devcontainer:dev-latest-local",
    "runArgs": [
        "--userns=keep-id",
        "--security-opt", "label=disable"
    ],
    "remoteUser": "vscode",
    "remoteEnv": {
        "PODMAN_USERNS": "keep-id"
    },
    "customizations": {
        "vscode": {
            "settings": {
                "python.defaultInterpreterPath": "/usr/local/bin/python",
                "python.languageServer": "Pylance",
                "extensions.ignoreRecommendations": true,
                "extensions.autoUpdate": false,
                "extensions.autoCheckUpdates": false
            }
        }
    },
    "updateRemoteUserUID": true,
    "overrideCommand": false
}

# Create a test file
echo "print('Hello from offline container!')" > test.py

# Run in container
podman run \
    -v ./test.py:/home/vscode/test.py:Z \
    -it offline-python-vscode-devcontainer:dev-latest-local \
    python /home/vscode/test.py

# Create project directory
mkdir -p ./my-python-project
cd ./my-python-project

# Create Python file
cat > main.py << 'EOF'
import pandas as pd
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
podman run \
    -v $(pwd):/home/vscode/project:Z \
    -it offline-python-vscode-devcontainer:dev-latest-local \
    python /home/vscode/project/main.py

# Run all tests
podman run \
    -v $(pwd):/home/vscode/project:Z \
    -it offline-python-vscode-devcontainer:dev-latest-local \
    pytest -v /home/vscode/project/tests/

# Run specific test file
podman run \
    -v $(pwd):/home/vscode/project:Z \
    -it offline-python-vscode-devcontainer:dev-latest-local \
    pytest -v /home/vscode/project/tests/test_specific.py

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 - The base runtime image provides the core Python environment, Oracle drivers, and offline package management capabilities.

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:

   # Inside the devcontainer
   pip install numpy matplotlib seaborn

2. For persistent packages: Add to your project's requirements.txt:

   numpy
   matplotlib
   seaborn
   # Your application-specific packages
   

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.

⚠️ 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
• 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
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.

Update .devcontainer/devcontainer.json:

{
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-toolsai.jupyter",
                "ms-vscode.vscode-json"
            ]
        }
    }
}

# 1. Pull image (online)
podman pull ghcr.io/opentechil/offline-python-vscode-devcontainer:latest

# 2. Save for offline transfer
podman save -o offline-python-devcontainer.tar \
    ghcr.io/opentechil/offline-python-vscode-devcontainer:latest

# 3. Transfer to air-gapped system
# (Use USB, network transfer, etc.)

# 4. Load on offline system
podman load -i offline-python-devcontainer.tar

# 5. Use offline
podman run -v ./project:/home/vscode/project:Z \
    -it ghcr.io/opentechil/offline-python-vscode-devcontainer:latest \
    python /home/vscode/project/app.py

• 🔐 Non-root execution: All processes run as vscode user
• 🛡️ SELinux compatible: Proper security contexts
• 🔒 No network access: Container runs in isolation
• 📋 Minimal attack surface: Only essential packages installed

See CHANGELOG.md for detailed version history and feature updates.

# Create temporary directory with more space
mkdir -p ~/podman-tmp
export TMPDIR=~/podman-tmp

# Then rebuild
podman build . -t offline-python-vscode-devcontainer:dev-latest-local

# Ensure proper SELinux context
podman run \
    -v ./project:/home/vscode/project:Z \
    -it offline-python-vscode-devcontainer:dev-latest-local \
    python /home/vscode/project/app.py

• 📖 Check AGENTS.md for development guidelines
• 🐛 Report issues
• 💬 Start a discussion

We welcome contributions! Please read our CONTRIBUTORS.md for detailed guidelines.

# 1. Create feature branch
git flow feature start your-feature

# 2. Make changes
# ... edit files ...

# 3. Test your changes
podman build . -t offline-python-vscode-devcontainer:test
podman run -it offline-python-vscode-devcontainer:test pytest -v

# 4. Commit and push
git add .
git commit -m "feat: add your feature"
git push origin feature/your-feature

# 5. Create Pull Request

• Follow Dockerfile best practices
• Use multi-stage builds
• Keep images small and secure
• Test thoroughly before submitting

This project is licensed under the MIT License - see the LICENSE file for details.

• Microsoft Dev Containers for the base images
• Podman for container runtime
• Python Software Foundation for Python
• All contributors who make this project better