{"id":29665802,"url":"https://github.com/pkramek/python-devcontainer","last_synced_at":"2026-05-06T18:33:26.037Z","repository":{"id":305520365,"uuid":"1023069454","full_name":"PKramek/python-devcontainer","owner":"PKramek","description":"🚀 Modern Python DevContainer template with UV, Ruff, and zero-config magic. Because life's too short for dependency hell. ","archived":false,"fork":false,"pushed_at":"2025-07-20T15:06:14.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-20T16:22:30.656Z","etag":null,"topics":["devcontainer","docker","docker-compose","pre-commit","python","ruff"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PKramek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-20T13:13:20.000Z","updated_at":"2025-07-20T14:56:26.000Z","dependencies_parsed_at":"2025-07-20T16:32:50.389Z","dependency_job_id":null,"html_url":"https://github.com/PKramek/python-devcontainer","commit_stats":null,"previous_names":["pkramek/python-devcontainer"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/PKramek/python-devcontainer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PKramek%2Fpython-devcontainer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PKramek%2Fpython-devcontainer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PKramek%2Fpython-devcontainer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PKramek%2Fpython-devcontainer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PKramek","download_url":"https://codeload.github.com/PKramek/python-devcontainer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PKramek%2Fpython-devcontainer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272013594,"owners_count":24858481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devcontainer","docker","docker-compose","pre-commit","python","ruff"],"created_at":"2025-07-22T14:38:27.950Z","updated_at":"2026-05-06T18:33:25.993Z","avatar_url":"https://github.com/PKramek.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐍 Python DevContainer Template\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![UV](https://img.shields.io/badge/uv-package%20manager-green.svg)](https://docs.astral.sh/uv/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![DevContainer](https://img.shields.io/badge/DevContainer-Ready-blue.svg)](https://code.visualstudio.com/docs/devcontainers/containers)\n[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n\n\u003e 🚀 **A modern, production-ready Python development environment using VS Code DevContainers with UV package management and comprehensive code quality tools.**\n\nThis template provides a complete, containerized Python development environment that works consistently across different machines and operating systems. Perfect for teams who want to standardize their development setup and onboard new developers quickly.\n\n## ✨ Features\n\n### 🏗️ **Modern Python Development**\n- **Python 3.12** - Latest stable Python version\n- **UV Package Manager** - Lightning-fast Python package installer and resolver\n- **PEP 621 Compliant** - Modern `pyproject.toml` configuration\n- **Development Dependencies** - Pre-configured with essential dev tools\n\n### 🐳 **Containerized Development Environment**\n- **VS Code DevContainer** - Complete development environment in a container\n- **Docker Compose Setup** - Multi-service architecture ready for databases, OTEL collectors, and other services\n- **Cross-platform Support** - Works on Intel, AMD, and Apple Silicon\n- **Instant Setup** - Zero configuration required for new team members\n\n### 🔧 **Code Quality \u0026 Developer Experience**\n- **Ruff** - Ultra-fast Python linter and formatter (replaces Black + isort + flake8)\n- **MyPy** - Static type checking for better code reliability\n- **Pre-commit Hooks** - Automated code quality checks before commits\n- **Security Scanning** - Bandit for security vulnerability detection\n- **Secret Detection** - Prevent accidental commits of sensitive data\n\n### 🛠️ **VS Code Integration**\n- **Rich Extensions** - Python, Ruff, MyPy, GitLens, GitHub Copilot, and more\n- **IntelliSense** - Advanced code completion and navigation\n- **Debugging Support** - Full debugging capabilities pre-configured\n- **Integrated Terminal** - All tools available in the integrated terminal\n\n### 🚀 **Multi-Service Architecture**\n- **Docker Compose Ready** - Easily add databases, message queues, OTEL collectors, and other services\n- **Service Networking** - Pre-configured backend network for service communication\n- **Environment Configuration** - Flexible environment variable management\n- **Development Scaling** - Support for complex local development scenarios\n\n## 📋 Table of Contents\n\n- [Quick Start](#-quick-start)\n- [Prerequisites](#-prerequisites)\n- [Installation](#-installation)\n- [Usage](#-usage)\n- [Project Structure](#-project-structure)\n- [Development Tools](#-development-tools)\n- [Code Quality](#-code-quality)\n- [Configuration](#-configuration)\n- [Adding Services](#-adding-services)\n- [Troubleshooting](#-troubleshooting)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🚀 Quick Start\n\n### Using GitHub Template\n\n1. **Click \"Use this template\"** button at the top of this repository\n2. **Clone your new repository**:\n   ```bash\n   git clone https://github.com/yourusername/your-repo-name.git\n   cd your-repo-name\n   ```\n3. **Open in VS Code** and select \"Reopen in Container\" when prompted\n4. **Start coding!** 🎉\n\n### One-Click Setup with Codespaces\n\n[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/yourusername/python-devcontainer?quickstart=1)\n\n## 📋 Prerequisites\n\nBefore you begin, ensure you have the following installed:\n\n### Required\n- **[Docker Desktop](https://www.docker.com/products/docker-desktop/)** (Latest version)\n- **[VS Code](https://code.visualstudio.com/)** (Latest version)\n- **[Dev Containers Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)** for VS Code\n\n### System Requirements\n- **Operating System**: Windows 10/11, macOS, or Linux\n- **Memory**: 8GB RAM minimum (16GB recommended)\n- **Storage**: 10GB free space minimum\n- **Architecture**: x86_64 or ARM64 (Apple Silicon supported)\n\n## 🛠️ Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/yourusername/python-devcontainer.git\ncd python-devcontainer\n```\n\n### 2. Open in VS Code\n\n```bash\ncode .\n```\n\n### 3. Reopen in Container\n\nWhen VS Code opens, you'll see a notification:\n\n\u003e **\"Folder contains a Dev Container configuration file. Reopen folder to develop in a container\"**\n\nClick **\"Reopen in Container\"** or:\n- Press `F1` → Type \"Dev Containers: Reopen in Container\"\n- Use Command Palette: `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS)\n\n### 4. Wait for Container Build\n\nThe first time will take a few minutes to:\n- Download the base Docker images\n- Install Python dependencies\n- Configure VS Code extensions\n- Set up the development environment\n\n## 📖 Usage\n\n### Running the Sample Application\n\n```bash\n# Test the sample application\npython main.py\n\n# Expected output:\n# Hello from python-devcontainer!\n```\n\n### Package Management with UV\n\n```bash\n# Install a new package\nuv add requests\n\n# Install development dependency\nuv add --dev pytest\n\n# Install from lock file\nuv sync\n\n# Update dependencies\nuv lock --upgrade\n\n# Show installed packages\nuv pip list\n```\n\n### Code Quality Tools\n\n```bash\n# Run linting\nruff check .\n\n# Auto-fix issues\nruff check --fix .\n\n# Format code\nruff format .\n\n# Type checking\nmypy main.py\n\n# Run all pre-commit hooks\npre-commit run --all-files\n\n# Security scan\nbandit -r .\n```\n\n## 📁 Project Structure\n\n```\npython-devcontainer/\n├── .devcontainer/\n│   ├── devcontainer.json      # VS Code DevContainer configuration\n│   ├── Dockerfile             # Python development environment\n│   ├── docker-compose.yml     # Multi-service setup\n│   ├── setup.sh              # Post-creation setup script\n│   └── .env.example          # Environment variables template\n├── .pre-commit-config.yaml    # Pre-commit hooks configuration\n├── pyproject.toml             # Python project configuration\n├── uv.lock                   # Dependency lock file\n├── main.py                   # Sample Python application\n└── README.md                 # This file\n```\n\n## 🔧 Development Tools\n\n### Included Tools\n\n| Tool | Purpose | Configuration |\n|------|---------|---------------|\n| **UV** | Package management | `pyproject.toml` |\n| **Ruff** | Linting \u0026 formatting | `pyproject.toml` |\n| **MyPy** | Type checking | `pyproject.toml` |\n| **Bandit** | Security scanning | `pyproject.toml` |\n| **PyUpgrade | automatically upgrade syntax | `pyproject.toml` |\n| **Pre-commit** | Git hooks | `.pre-commit-config.yaml` |\n\n### VS Code Extensions\n\nPre-installed extensions for the best development experience:\n\n- **Python** - Python language support\n- **Ruff** - Python linting and formatting\n- **MyPy Type Checker** - Static type checking\n- **Python Typehint** - Enhanced type hint support\n- **Python Indent** - Correct Python indentation\n- **IntelliCode** - AI-assisted development\n- **GitLens** - Enhanced Git capabilities\n- **GitHub Copilot** - AI pair programming\n- **TODO Tree** - Task management\n\n## ✅ Code Quality\n\n### Automated Quality Checks\n\nThis template enforces code quality through multiple layers:\n\n#### Pre-commit Hooks\n- **File checks**: Large files, merge conflicts, YAML/TOML syntax\n- **Security**: Private key detection, secret scanning\n- **Python**: AST validation, debug statement detection\n- **Formatting**: Trailing whitespace, end-of-file fixes\n- **Code Quality**: Ruff linting and formatting\n\n#### Static Analysis\n- **Ruff**: Comprehensive linting (replaces flake8, isort, and more)\n- **MyPy**: Static type checking for better code reliability\n- **Bandit**: Security vulnerability scanning\n\n#### Configuration\n\nAll tools are configured in `pyproject.toml`:\n\n```toml\n[tool.ruff]\nline-length = 88\ntarget-version = \"py312\"\n\n[tool.mypy]\npython_version = \"3.12\"\nstrict = true\n\n[tool.bandit]\nexclude_dirs = [\"tests\"]\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nThe template includes an `.env.example` file for environment variable configuration. Copy and customize it for your needs:\n\n```bash\ncp .devcontainer/.env.example .devcontainer/.env\n```\n\nAdd your environment variables to the `.env` file:\n\n```bash\n# Example environment variables\nAPI_KEY=your_api_key_here\nDATABASE_URL=postgresql://user:pass@host:port/dbname\nDEBUG=true\n```\n\n### Customizing the Environment\n\n#### Adding Dependencies\n\n```bash\n# Production dependency\nuv add package-name\n\n# Development dependency  \nuv add --dev package-name\n\n# Optional dependency group\nuv add --group group-name package-name\n```\n\n#### VS Code Settings\n\nCustomize VS Code settings in `.devcontainer/devcontainer.json`:\n\n```json\n{\n  \"customizations\": {\n    \"vscode\": {\n      \"settings\": {\n        \"python.defaultInterpreterPath\": \"/usr/local/bin/python\"\n      },\n      \"extensions\": [\n        \"ms-python.python\"\n      ]\n    }\n  }\n}\n```\n\n## 🐳 Adding Services\n\nThis template uses Docker Compose, making it easy to add additional services for local development. The setup includes a pre-configured backend network for service communication.\n\n### Example: Adding a Database\n\nAdd a PostgreSQL database to your `docker-compose.yml`:\n\n```yaml\nservices:\n  python-devcontainer:\n    # ... existing configuration ...\n    depends_on:\n      - postgres\n\n  postgres:\n    image: postgres:15\n    environment:\n      POSTGRES_DB: myapp\n      POSTGRES_USER: postgres\n      POSTGRES_PASSWORD: postgres\n    ports:\n      - \"5432:5432\"\n    volumes:\n      - postgres_data:/var/lib/postgresql/data\n    networks:\n      - backend\n\nvolumes:\n  postgres_data:\n```\n\n### Example: Adding Redis Cache\n\n```yaml\nservices:\n  # ... existing services ...\n\n  redis:\n    image: redis:7-alpine\n    ports:\n      - \"6379:6379\"\n    networks:\n      - backend\n```\n\n### Example: Adding OTEL Collector\n\n```yaml\nservices:\n  # ... existing services ...\n\n  otel-collector:\n    image: otel/opentelemetry-collector:latest\n    command: [\"--config=/etc/otel-collector-config.yml\"]\n    volumes:\n      - ./otel-collector-config.yml:/etc/otel-collector-config.yml\n    ports:\n      - \"8888:8888\"   # Prometheus metrics\n      - \"8889:8889\"   # Prometheus exporter metrics\n      - \"13133:13133\" # health_check extension\n      - \"4317:4317\"   # OTLP gRPC receiver\n      - \"4318:4318\"   # OTLP HTTP receiver\n    networks:\n      - backend\n```\n\n### Service Communication\n\nServices can communicate using their service names as hostnames:\n\n```python\n# Connect to PostgreSQL from Python container\nimport psycopg2\n\nconn = psycopg2.connect(\n    host=\"postgres\",  # Service name as hostname\n    port=5432,\n    database=\"myapp\",\n    user=\"postgres\",\n    password=\"postgres\"\n)\n\n# Connect to Redis\nimport redis\n\nr = redis.Redis(host=\"redis\", port=6379, db=0)\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n#### Container Won't Start\n```bash\n# Rebuild container\nCtrl+Shift+P → \"Dev Containers: Rebuild Container\"\n\n# Or rebuild without cache\nCtrl+Shift+P → \"Dev Containers: Rebuild Container Without Cache\"\n```\n\n#### Python Package Issues\n```bash\n# Reinstall all packages\nuv sync --refresh\n\n# Clear UV cache\nuv cache clean\n```\n\n#### Service Connection Issues\n```bash\n# Check all container status\ndocker ps\n\n# View logs for specific service\ndocker logs python-devcontainer-\u003cservice-name\u003e-1\n\n# Restart specific service\ndocker restart python-devcontainer-\u003cservice-name\u003e-1\n\n# Check network connectivity\ndocker network ls\ndocker network inspect python-devcontainer_backend\n```\n\n#### Permission Issues (Linux/macOS)\n```bash\n# Fix file permissions\nsudo chown -R $USER:$USER .\n```\n\n### Performance Tips\n\n- **Enable Docker BuildKit** for faster builds\n- **Allocate more memory** to Docker (8GB recommended)\n- **Use SSD storage** for better I/O performance\n- **Close unnecessary VS Code windows** to save resources\n- **Use Docker volumes** for data that needs to persist\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our contributing guidelines:\n\n### Getting Started\n\n1. **Fork** the repository\n2. **Create** a feature branch: `git checkout -b feature/amazing-feature`\n3. **Make** your changes\n4. **Run** tests and quality checks: `pre-commit run --all-files`\n5. **Commit** your changes: `git commit -m 'Add amazing feature'`\n6. **Push** to the branch: `git push origin feature/amazing-feature`\n7. **Open** a Pull Request\n\n### Development Guidelines\n\n- Follow **PEP 8** style guidelines (enforced by Ruff)\n- Add **type hints** to all functions\n- Write **tests** for new functionality\n- Update **documentation** as needed\n- Ensure all **quality checks pass**\n\n### Code of Conduct\n\nThis project follows the [Contributor Covenant](https://www.contributor-covenant.org/) Code of Conduct.\n\n## 📚 Resources\n\n### Documentation\n- [VS Code DevContainers](https://code.visualstudio.com/docs/devcontainers/containers)\n- [UV Package Manager](https://docs.astral.sh/uv/)\n- [Ruff Linter](https://docs.astral.sh/ruff/)\n- [Pre-commit Hooks](https://pre-commit.com/)\n- [Docker Compose](https://docs.docker.com/compose/)\n- [Python Type Hints](https://docs.python.org/3/library/typing.html)\n\n### Learning Materials\n- [Python Best Practices](https://realpython.com/python-code-quality/)\n- [Docker for Developers](https://docs.docker.com/get-started/)\n- [Docker Compose Tutorial](https://docs.docker.com/compose/gettingstarted/)\n\n## 🌟 Why This Template?\n\n### For Individual Developers\n- ⚡ **Zero setup time** - Start coding immediately\n- 🔧 **Best practices built-in** - Modern tooling pre-configured\n- 🛡️ **Quality assurance** - Automated checks prevent issues\n- 📚 **Learning opportunity** - Discover modern Python tooling\n\n### For Teams\n- 🎯 **Consistent environments** - Same setup for everyone\n- 🚀 **Faster onboarding** - New team members productive in minutes\n- 👥 **Better collaboration** - Shared tooling and standards\n- 🔒 **Security by default** - Built-in security scanning\n\n### For Projects\n- 🏗️ **Production-ready** - Follows industry best practices\n- 📈 **Scalable foundation** - Easy to extend and customize\n- 🧪 **Testing-friendly** - Set up for comprehensive testing\n- 📦 **Deployment-ready** - Container-based development to production\n- 🐳 **Multi-service ready** - Easy integration with databases, caches, and other services\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **UV Team** for the amazing package manager\n- **Astral** for Ruff and the excellent Python tooling\n- **Microsoft** for VS Code and DevContainers\n- **Docker** for containerization technology\n- **Python Community** for the incredible ecosystem\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⬆ Back to Top](#-python-devcontainer-template)**\n\nMade with ❤️ for the Python community\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkramek%2Fpython-devcontainer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpkramek%2Fpython-devcontainer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkramek%2Fpython-devcontainer/lists"}