F055: DevContainer with Docker Compose for Parallel Worktree Development

[pocky]

F055: DevContainer with Docker Compose for Parallel Worktree Development

User Stories

US1: Isolated Development Environment (P1 - Must Have)

As a developer,
I want a devcontainer configuration that works with Docker Compose,
So that I can have a fully isolated, reproducible development environment with all dependencies pre-configured.

Acceptance Scenarios:

• Given I have Docker and VS Code installed, when I open the project in VS Code, then I am prompted to reopen in container
• Given I open the project in devcontainer, when the container starts, then all Go tools (golangci-lint, go test, etc.) are available
• Given I am in the devcontainer, when I run make test, then all tests execute without missing dependencies
• Given I am in the devcontainer, when I run awf --help, then the CLI responds correctly

Independent Test: Clone fresh repo, open in devcontainer, run make build && make test successfully

US2: Parallel Worktree Support (P1 - Must Have)

As a developer working on multiple features simultaneously,
I want each git worktree to have its own isolated devcontainer instance,
So that I can develop and test multiple features in parallel without environment conflicts.

Acceptance Scenarios:

• Given I have two worktrees (main and feature-branch), when I open each in VS Code, then each gets its own container instance
• Given two containers are running for different worktrees, when I modify dependencies in one, then the other remains unaffected
• Given containers for multiple worktrees exist, when I run tests in worktree A, then worktree B's state is unchanged
• Given I have limited resources, when I close a worktree's VS Code window, then its container resources are released

Independent Test: Create worktree, open both main and worktree in separate VS Code windows, verify isolated containers

US3: Service Dependencies via Compose (P2 - Should Have)

As a developer,
I want Docker Compose to manage external service dependencies (databases, caches),
So that I have consistent test infrastructure without manual setup.

Acceptance Scenarios:

• Given I need SQLite for tests, when the devcontainer starts, then SQLite is available and configured
• Given Compose defines service dependencies, when I run integration tests, then all required services are accessible
• Given I stop the devcontainer, when I restart it, then persistent test data (if any) is preserved in volumes

Independent Test: Run integration tests requiring SQLite, verify database operations succeed

US4: Resource-Efficient Multi-Container Setup (P3 - Nice to Have)

As a developer with limited machine resources,
I want containers to share base images and use resource limits,
So that running multiple worktree containers doesn't overwhelm my system.

Acceptance Scenarios:

• Given I have 3 worktree containers running, when I check resource usage, then total memory is under 8GB
• Given containers use the same base image, when a second container starts, then it reuses cached layers

Independent Test: Start 3 worktree containers, verify combined memory usage with docker stats

---

Requirements

Functional Requirements

• FR-001: Devcontainer must use Docker Compose for orchestration (not standalone Dockerfile)
• FR-002: Each worktree must spawn isolated container instances using unique project names
• FR-003: Devcontainer must include Go 1.21+, make, git, golangci-lint, and CGO dependencies (SQLite)
• FR-004: VS Code extensions (Go, GitLens) must be pre-installed in devcontainer
• FR-005: Container must mount worktree directory with correct permissions for the development user
• FR-006: Docker Compose must support dynamic project naming based on worktree path

Non-Functional Requirements

• NFR-001: Container startup time < 60 seconds on cached images
• NFR-002: Memory usage per container < 2GB under normal development load
• NFR-003: Devcontainer configuration must work on Linux, macOS (Docker Desktop), and WSL2
• NFR-004: No secrets or credentials stored in devcontainer configuration files

---

Success Criteria

• All P1 user stories implemented and tested
• All P2 user stories implemented and tested
• Devcontainer opens successfully in VS Code
• make build && make test passes inside container
• Two worktrees can run isolated containers simultaneously
• Documentation updated in README or CONTRIBUTING.md
• Works on Linux, macOS, and WSL2

---

Key Entities

Entity	Description	Attributes
devcontainer.json	VS Code devcontainer configuration	dockerComposeFile, service, workspaceFolder, extensions
docker-compose.yml	Compose orchestration for dev services	services, volumes, networks
Dockerfile.dev	Development container image definition	base image, tools, user setup
.env.devcontainer	Environment variables for container	GO_VERSION, UID, GID

---

Metadata

• Status: backlog
• Version: v0.4.0
• Priority: medium
• Estimation: M

Dependencies

• Blocked by: none
• Unblocks: none

Clarifications

Section populated during clarify step with resolved ambiguities.

• Worktree isolation achieved via ${localWorkspaceFolderBasename} in Docker Compose project name
• SQLite is the only external dependency currently needed (CGO requirement)
• No remote container registry required; images built locally

Notes

Technical Approach

.devcontainer/
├── devcontainer.json # VS Code configuration
├── docker-compose.yml # Compose orchestration
├── Dockerfile.dev # Dev image (Go + tools)
└── .env.example # Template for local overrides

Worktree Isolation Strategy

Docker Compose project name derived from worktree folder name:
json
{
"dockerComposeFile": "docker-compose.yml",
"service": "dev",
"workspaceFolder": "/workspace",
"runArgs": ["--name", "${localWorkspaceFolderBasename}-dev"]
}

Required VS Code Extensions

• golang.go
• eamodio.gitlens
• ms-azuretools.vscode-docker

CGO Considerations

SQLite requires CGO. Devcontainer must include:

• gcc
• musl-dev or libc6-dev
• sqlite-dev