Python 3.13 DevContainer Template

A production-ready DevContainer template with Python 3.13, Claude Code CLI, Playwright, and optional network security.

Quick Start

1. Copy to your project:

   ./create-devcontainer.sh /path/to/your/project

2. Open in VS Code:

   • Install the "Dev Containers" extension if not already installed
   • Open your project folder
   • VS Code will detect .devcontainer/ and prompt to reopen in container
   • Click "Reopen in Container" (or use Command Palette → "Dev Containers: Reopen in Container")

3. Start developing:

   • All tools are pre-installed and ready to use
   • See CLAUDE.md for detailed guidance

What's Included

• Python 3.13 - Latest Python with uv package manager for fast dependency management
• Claude Code CLI - AI-powered development assistant
• Playwright - Browser automation with Chromium, Firefox, and WebKit pre-installed
• Node.js 20.x - JavaScript runtime and npm package manager
• Development Tools:
  • git with git-delta for enhanced diffs
  • GitHub CLI (gh)
  • ZSH with Powerline10k theme
  • fzf for fuzzy file and history searching
  • vim and nano editors
• Optional Firewall - Whitelist-based network security for sensitive development

Configuration Options

The create-devcontainer.sh script supports the following options:

# Basic usage
./create-devcontainer.sh /path/to/project

# Custom timezone
./create-devcontainer.sh --timezone "UTC" /path/to/project

# Custom container name
./create-devcontainer.sh --name "MyApp Dev" /path/to/project

# Preview changes without applying
./create-devcontainer.sh --dry-run /path/to/project

# Show help
./create-devcontainer.sh --help

Available Options

• --timezone TZ - Set container timezone (default: America/Los_Angeles)
• --name NAME - Custom container name (default: derived from directory name)
• --dry-run - Preview changes without making them
• --help - Show usage information

Testing This Template

The devcontainer_tests/ directory contains a comprehensive validation test suite. These tests are for template development and validation only - they are not meant to be copied to projects using the template.

See devcontainer_tests/TESTING.md for details on:

• Running tests from inside the container
• Running integration tests from the host machine
• What each test validates

Documentation

• CLAUDE.md - Comprehensive guide for Claude Code, including architecture details and development commands
• devcontainer_tests/TESTING.md - Test suite documentation

Customization

After copying the template to your project, you can customize:

devcontainer.json

• Add or remove VS Code extensions in the extensions array
• Modify port forwarding in the forwardPorts array
• Adjust lifecycle hooks (postCreateCommand, postStartCommand)
• Change container name or workspace folder

Dockerfile

• Install additional system packages with apt-get install
• Change Python version by modifying the base image
• Change Node.js version by updating the NodeSource setup script
• Add project-specific tools

init-firewall.sh

To whitelist additional domains for network access, edit the domain loop around line 67:

for domain in \
    "registry.npmjs.org" \
    "api.anthropic.com" \
    "your-new-domain.com"; do
    # ...
done

Then run inside the container:

sudo /usr/local/bin/init-firewall.sh

Project Structure

.
├── .devcontainer/              # Core template (copied to projects)
│   ├── devcontainer.json       # VS Code DevContainer configuration
│   ├── Dockerfile              # Container image definition
│   ├── init-firewall.sh        # Optional network security script
│   └── post-create.sh          # Post-creation validation
│
├── devcontainer_tests/         # Template validation tests (not copied)
│   ├── tests/                  # Test suite
│   ├── test_fixtures/          # Sample code for testing
│   └── TESTING.md              # Test documentation
│
├── create-devcontainer.sh      # Script to copy template to projects
├── CLAUDE.md                   # Detailed guide for Claude Code
└── README.md                   # This file

Requirements

• VS Code with the Dev Containers extension
• Docker Desktop or Docker Engine
• Host OS: macOS, Linux, or Windows with WSL2

Troubleshooting

Container fails to build

• Ensure Docker is running
• Check Docker has sufficient resources (4GB RAM minimum, 8GB recommended)
• Try rebuilding without cache: Command Palette → "Dev Containers: Rebuild Container Without Cache"

Network requests failing after enabling firewall

The firewall uses a whitelist approach. If legitimate requests are blocked:

1. Check current firewall rules:

   sudo iptables -L -v -n

2. Check kernel messages for rejected connections:

   dmesg | tail -20

3. Add the domain to the whitelist in .devcontainer/init-firewall.sh

4. Re-run the firewall script:

   sudo /usr/local/bin/init-firewall.sh

Playwright browsers not found

Browsers are pre-installed during the image build. If missing, manually install inside the container:

playwright install chromium firefox webkit

License

[Choose your license - MIT, Apache 2.0, etc.]

Contributing

This is a template repository. Feel free to fork and customize for your needs!