MIGRATION.md

Migration Guide: Makefile/venv → Dev Containers

This guide helps you migrate from the traditional Makefile/venv setup to the new Dev Container development environment.

Why Migrate?

Benefits of Dev Containers

• Zero setup: One-click development environment
• Consistency: Same environment across all developers and CI/CD
• Isolation: No conflicts with host system packages
• VS Code integration: Seamless debugging, testing, and development tools
• Docker alignment: Development environment matches production container

Before (Makefile/venv)

make setup           # Manual setup required
source venv/bin/activate  # Manual activation
make run            # Run commands

After (Dev Container)

# Just open in VS Code and reopen in container
# Everything is automatic!
python app.py       # Direct commands

Migration Steps

1. Prerequisites

Install required tools:

• Docker
• VS Code
• Dev Containers extension

2. Clean Up Old Environment (Optional)

If you want to start fresh:

# Clean up old virtual environment and generated files
make clean

# Or manually:
rm -rf venv/
rm -rf data/temp/* data/output/*
rm -rf __pycache__ .pytest_cache

3. Open in Dev Container

1. Open VS Code:

   code .
   

2. Reopen in Container:

   • Press F1
   • Type "Dev Containers: Reopen in Container"
   • Select the command
   • Wait for container to build and setup to complete

3. First-time setup:

   • Container builds automatically (5-10 minutes first time)
   • VOICEVOX Core downloads automatically
   • All dependencies install automatically
   • Pre-commit hooks setup automatically

4. Verify Setup

Test that everything works:

# Run the application
python app.py

# Run tests
pytest tests/

# Check linting
flake8 . && mypy .

5. Update Your Workflow

Old Workflow

source venv/bin/activate  # Activate environment
make run                  # Run application
make test                 # Run tests
make lint                 # Run linting
make format               # Format code
deactivate               # Deactivate environment

New Workflow

# No activation needed - just use commands directly
python app.py            # Run application
pytest tests/            # Run tests
flake8 . && mypy .       # Run linting
black . && isort .       # Format code

# Or use VS Code tasks:
# Ctrl+Shift+P → "Tasks: Run Task" → Select task

Command Mapping

Old (Make)	New (Direct)	VS Code Task
make setup	Automatic via devcontainer	N/A
make run	python app.py	"Run Yomitalk App"
make test	pytest tests/	"Run All Tests"
make test-unit	pytest tests/unit/	"Run Unit Tests"
make test-e2e	E2E_TEST_MODE=true pytest tests/e2e/	"Run E2E Tests"
make lint	flake8 . && mypy .	"Run Linting"
make format	black . && isort .	"Format Code"
make pre-commit-run	pre-commit run --all-files	"Run Pre-commit"
make clean	"Dev Containers: Rebuild Container"	N/A

VS Code Integration

Tasks

Access via Ctrl+Shift+P → "Tasks: Run Task":

• Run Yomitalk App
• Run All Tests
• Run Unit Tests
• Run E2E Tests
• Format Code
• Run Linting
• Run Pre-commit

Debugging

• F5: Debug current configuration
• Ctrl+F5: Run without debugging
• Configurations available for app, unit tests, E2E tests

Extensions

Automatically installed and configured:

• Python
• Black Formatter
• isort
• Flake8
• MyPy Type Checker
• Jupyter
• Jinja
• Playwright

Troubleshooting

Container Won't Start

1. Ensure Docker is running
2. Check Docker Desktop has enough resources (4GB+ RAM recommended)
3. Try "Dev Containers: Rebuild Container"

VOICEVOX Download Fails

# Run setup script manually in container terminal
bash .devcontainer/setup.sh

Port 7860 Not Accessible

1. Check VS Code port forwarding tab
2. Ensure app binds to 0.0.0.0:7860, not localhost:7860
3. Check firewall settings

Slow Performance

1. Use Docker volumes for large directories (already configured)
2. Increase Docker Desktop resource allocation
3. Consider using WSL2 backend on Windows

Permission Issues

# In container terminal
sudo chown -R vscode:vscode /workspace

Keeping Both Approaches

You can use both approaches simultaneously:

Dev Container (Recommended)

• Daily development
• Debugging and testing
• Code review and collaboration

Makefile (Backup)

• CI/CD environments without container support
• Quick local testing
• Legacy system compatibility

The Makefile is still maintained and functional for those who prefer it or need it for specific scenarios.

Getting Help

• Dev Container Issues: See .devcontainer/README.md
• Application Issues: See main README.md
• Architecture Questions: See docs/design.md
• Development Guidelines: See CLAUDE.md

Benefits You'll Notice

Immediate

• No more virtual environment management
• Consistent Python environment
• Pre-configured development tools
• Integrated VS Code experience

Long-term

• Same environment across team members
• Easier onboarding for new developers
• Better CI/CD environment alignment
• Simplified Docker deployment