|
| 1 | +--- |
| 2 | +name: devcontainer-run |
| 3 | +description: >- |
| 4 | + Detect the running Bucketeer dev container (local VS Code devcontainer or |
| 5 | + GitHub Codespace) and run commands inside it. Use this whenever a task should |
| 6 | + run in the dev container environment — make targets, builds, tests, kubectl / |
| 7 | + helm / minikube commands, checking whether the container is up — or when the |
| 8 | + user says "devcontainer-run", "devc", "dev container", "devcontainer", "codespace", or "run this |
| 9 | + inside the container". Also use it when a task needs tools the container |
| 10 | + guarantees but the host may lack (protoc 23.4, mockgen, protolock, helm, |
| 11 | + kubectl, minikube). devcontainer-generate and devcontainer-deploy build on this skill. |
| 12 | +--- |
| 13 | + |
| 14 | +# devcontainer-run — run commands inside the Bucketeer dev container |
| 15 | + |
| 16 | +The dev container is the canonical Bucketeer development environment: Ubuntu with |
| 17 | +docker-in-docker, minikube + helm + kubectl, protoc v23.4, and Go tooling in |
| 18 | +`/home/codespace/go-tools/bin` (a persistent volume, NOT on PATH in plain |
| 19 | +non-login shells). The workspace is `/workspaces/bucketeer`, the user is |
| 20 | +`codespace` (passwordless sudo). |
| 21 | + |
| 22 | +Human-facing documentation for this environment lives in `DEVELOPMENT.md` |
| 23 | +("Working with the dev container from the host" and the Minikube sections); |
| 24 | +this skill is the Claude-oriented operational version — when changing one, |
| 25 | +keep the other in sync. |
| 26 | + |
| 27 | +## How to run anything inside it |
| 28 | + |
| 29 | +Always go through the wrapper script — it finds the container and sets up PATH: |
| 30 | + |
| 31 | +```bash |
| 32 | +# Where is the container, and is the environment healthy? |
| 33 | +bash .claude/skills/devcontainer-run/scripts/exec.sh status |
| 34 | + |
| 35 | +# Run any command in /workspaces/bucketeer inside the container |
| 36 | +bash .claude/skills/devcontainer-run/scripts/exec.sh 'make build-api' |
| 37 | +bash .claude/skills/devcontainer-run/scripts/exec.sh 'kubectl get pods' |
| 38 | +``` |
| 39 | + |
| 40 | +Detection order (the script handles all of this): |
| 41 | +1. Already inside the container (`/workspaces/bucketeer` exists, user `codespace`) → run directly. |
| 42 | +2. Local devcontainer → `docker ps` filtered by label `devcontainer.local_folder=<repo root>`, exec via `docker exec`. |
| 43 | +3. GitHub Codespace → `gh codespace list` (needs the `codespace` auth scope), exec via `gh codespace ssh`. |
| 44 | + |
| 45 | +If more than one available Bucketeer codespace matches (a fork is also named |
| 46 | +`bucketeer`, or you keep several), the script refuses to guess and exits 2 with |
| 47 | +the list — pick one with `export BUCKETEER_CODESPACE=<name>`. |
| 48 | + |
| 49 | +Exit code 2 means no container was found (or the codespace was ambiguous); the |
| 50 | +script prints how to start one. |
| 51 | +Don't fall back to running the command on the host in that case — tell the user |
| 52 | +and let them choose, because host tool versions (especially protoc) may differ. |
| 53 | + |
| 54 | +## Local devcontainer vs Codespace — the one difference that matters |
| 55 | + |
| 56 | +- **Local devcontainer**: `/workspaces/bucketeer` is a bind mount of the host |
| 57 | + repo. Files generated inside appear in the host working tree immediately. |
| 58 | +- **Codespace**: a separate clone. Generated or edited files stay in the |
| 59 | + codespace. To get them back: commit and push from inside, or |
| 60 | + `gh codespace cp 'remote:/workspaces/bucketeer/<path>' <local-path>`. |
| 61 | + Always tell the user which mode you're in when file changes are involved |
| 62 | + (`status` prints it). |
| 63 | + |
| 64 | +## Environment facts and gotchas |
| 65 | + |
| 66 | +- Long commands (image builds, deploys) can take many minutes — use a generous |
| 67 | + Bash timeout (600000) or `run_in_background`. |
| 68 | +- `dockerd` inside the container is started by the post-attach hook, but that |
| 69 | + only fires when an editor attaches. If `status` says it's not running: |
| 70 | + `bash .claude/skills/devcontainer-run/scripts/exec.sh 'nohup sudo dockerd > /tmp/dockerd.log 2>&1 & sleep 5 && docker info > /dev/null && echo ok'` |
| 71 | +- minikube must be started with `make start-minikube`, never `minikube start` |
| 72 | + directly (the make target restores the cluster config and localenv services). |
| 73 | + Note: `make start-minikube` intentionally **exits 1 if minikube is already |
| 74 | + running** — check `minikube status` first instead of treating that as failure. |
| 75 | +- `web-gateway.bucketeer.io` / `api-gateway.bucketeer.io` resolve via the |
| 76 | + container's own `/etc/hosts` (pointed at `minikube ip`). Health checks with |
| 77 | + curl against those hosts must run *inside* the container, not on the host. |
| 78 | +- If go-tools are missing or permissions look broken, the fix is the setup |
| 79 | + script: `bash .devcontainer/setup.sh` (idempotent, cache-aware). |
| 80 | +- **Never run kubectl/helm bare on the host for dev work.** The host's kubectl |
| 81 | + context may point at a real GKE cluster, not minikube — always go through the |
| 82 | + wrapper so commands hit the cluster inside the container. |
| 83 | +- The host may also run a docker-compose Bucketeer stack in parallel |
| 84 | + (`docker-compose/compose.yml`). That is a different environment — this skill |
| 85 | + is only about the dev container / minikube world. |
0 commit comments