feat: add local-dev-setup skill for automated development environment#82
Conversation
- Automates complete local development environment initialization - Opens SSH tunnel to remote PostgreSQL (reads from .env) - Starts Docker Compose with all services - Validates prerequisites and performs health checks - Provides comprehensive documentation and troubleshooting guide Skill includes: - SKILL.md: Main skill definition and metadata - setup-local-dev.sh: 500+ line orchestration script with colored output - README.md: Portuguese documentation for usage - ARCHITECTURE.md: Technical deep-dive - TROUBLESHOOTING.md: Comprehensive debugging guide - evals.json: Test cases for validation - .env.example: Configuration template Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Moved docker-compose.yaml from project root to .claude/skills/local-dev-setup/assets/ - Updated setup-local-dev.sh script to reference the docker-compose file in skill assets - Script now dynamically determines asset location based on script directory - This makes the skill self-contained and independent from project structure Benefits: - Skill owns all its configuration files (docker-compose, .env.example, etc) - Easier to maintain and version the skill separately - Clear separation between project root and skill-specific infrastructure Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Updated docker-compose.yaml to use ${PROJECT_ROOT} variable for build contexts
- Enables dynamic path resolution when skill runs from any directory
- Script exports PROJECT_ROOT to docker-compose environment
- Removed docker-compose.yaml from project root (now in skill assets)
This ensures the skill is completely self-contained and can be run
independently without relying on repository structure.
Changes:
- setup-local-dev.sh: export PROJECT_ROOT and pass to docker-compose
- docker-compose.yaml: use ${PROJECT_ROOT} for ./frontend and ./backend
- Cleaned up redundant config location checks
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bdaa976062
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - DD_TAGS="app:portfolio,tech:python,role:backend,env:local" | ||
| - DD_RUNTIME_METRICS_ENABLED=true | ||
| - POSTGRES_HOST=192.168.15.8 | ||
| - POSTGRES_HOST=host.docker.internal |
There was a problem hiding this comment.
The backend now depends on POSTGRES_HOST=host.docker.internal for database access through the SSH tunnel, but unlike frontend it has no extra_hosts entry mapping host.docker.internal to host-gateway. On Linux Docker engines this hostname is not injected automatically, so the backend cannot resolve the DB host and the app fails to connect even though the tunnel is up.
Useful? React with 👍 / 👎.
| # Wait for backend to be ready | ||
| log_info "Checking backend health at $BACKEND_HEALTH_URL..." | ||
| while [ $attempt -lt $MAX_HEALTH_CHECK_ATTEMPTS ]; do | ||
| if curl -s "$BACKEND_HEALTH_URL" > /dev/null 2>&1; then |
There was a problem hiding this comment.
The health loops treat any HTTP response as success because they use curl -s without --fail; curl --help all documents -f, --fail as the flag that fails on HTTP errors. As written, a 500/404 response from backend or frontend will still mark the service as healthy, so the setup can report success while the app is actually broken.
Useful? React with 👍 / 👎.
|
|
||
| # Show Docker Compose status | ||
| echo -e "${BLUE}║${NC} ${GREEN}Docker Services:${NC}" | ||
| docker-compose ps | tail -n +2 | while read line; do |
There was a problem hiding this comment.
The stack is started with docker-compose -f "$SKILL_COMPOSE_FILE" -p portfolio up -d, but status output later runs plain docker-compose ps. Because this commit moved the compose file out of the repo root and uses a custom project name, ps targets the wrong/default project (or no config file), so the reported service status is incomplete or incorrect for the stack the script just launched.
Useful? React with 👍 / 👎.
1 participant
Summary
This PR introduces the local-dev-setup skill - a comprehensive automation for setting up the complete local development environment with SSH tunnel to remote PostgreSQL and Docker Compose orchestration.
Key Features
What Was Changed
New Files
.claude/skills/local-dev-setup/SKILL.md- Skill definition and metadata.claude/skills/local-dev-setup/scripts/setup-local-dev.sh- 500+ line orchestration script.claude/skills/local-dev-setup/README.md- Portuguese usage guide.claude/skills/local-dev-setup/references/ARCHITECTURE.md- Technical deep-dive.claude/skills/local-dev-setup/references/TROUBLESHOOTING.md- Debugging guide.claude/skills/local-dev-setup/references/.env.example- Configuration template.claude/skills/local-dev-setup/evals/evals.json- Test cases.claude/skills/local-dev-setup/assets/docker-compose.yaml- Self-contained compose fileModified Files
.claude/settings.json- Claude Code configurationRemoved Files
docker-compose.yaml- Moved to skill assets for self-containmentHow It Works
POSTGRES_HOSTfrom.envssh -g -L 0.0.0.0:5432:localhost:5432 root@{POSTGRES_HOST}docker-compose up -dUsage
Simply tell Claude Code:
The skill automatically detects relevance and executes the complete setup workflow.
Architecture Highlights
.claude/skills/local-dev-setup/${PROJECT_ROOT}variable for portabilityTesting
Skill has been tested and verified to:
.envBenefits
Co-Authored-By: Claude Haiku 4.5 noreply@anthropic.com