docs(docker): add toolbox compose template

[axobase001]

Fixes #2217

Summary:

• add a reusable docker compose toolbox template for opt-in sudo/dev packages/custom CA workflows
• document per-project image and .deepseek volume settings for independent project state
• keep the default GHCR image contract minimal and non-root

Validation:

• DEEPSEEK_API_KEY=dummy docker compose -f docs/examples/compose.toolbox.yml config

Greptile Summary

This PR adds a reusable docker compose entry point for the opt-in toolbox workflow and documents it in DOCKER.md. Both previously flagged issues (the CODEWHALE_WORKSPACE silent mis-mount and the :--induced empty-string passthrough for optional env vars) have been corrected: CODEWHALE_WORKSPACE and DEEPSEEK_API_KEY now use :? to fail fast, and DEEPSEEK_BASE_URL/DEEPSEEK_NO_COLOR use bare variable references so they are only forwarded when set on the host.

• compose.toolbox.yml: new Compose template that builds from Dockerfile.toolbox, enforces required variables, and names the state volume explicitly via CODEWHALE_HOME_VOLUME so project isolation is intentional rather than accidental.
• DOCKER.md: new subsection under "Opt-in toolbox/custom image" showing the exact command, per-project variable strategy, and links to the compose and Dockerfile examples.

Confidence Score: 5/5

Safe to merge — documentation and a new compose template with no runtime logic changes to the core application.

Both changes are additive: a new compose template and a documentation subsection. The compose file correctly uses :? mandatory validation for the two variables that previously had risky defaults, and the optional env vars use bare references. The build context and Dockerfile path resolve correctly relative to the compose file's location within the repository. No application code is touched.

No files require special attention.

Important Files Changed

Filename	Overview
docs/examples/compose.toolbox.yml	New Docker Compose template for the opt-in toolbox workflow; uses :? mandatory validation for DEEPSEEK_API_KEY and CODEWHALE_WORKSPACE, bare variable passthrough for optional vars, and explicit volume naming — previously flagged issues have been addressed.
docs/DOCKER.md	Adds a 'Compose toolbox template' subsection under the existing opt-in toolbox section; documents usage, per-project image/volume variables, and links to the new compose file and existing Dockerfile.toolbox.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["User runs:\ndocker compose -f compose.toolbox.yml run --rm codewhale"] --> B{CODEWHALE_WORKSPACE set?}
    B -- No --> C["Compose errors out\n(:? mandatory validation)"]
    B -- Yes --> D{DEEPSEEK_API_KEY set?}
    D -- No --> E["Compose errors out\n(:? mandatory validation)"]
    D -- Yes --> F{CODEWHALE_TOOLBOX_IMAGE\nimage exists locally?}
    F -- No --> G["docker build\ncontext: repo root\nDockerfile: docs/examples/Dockerfile.toolbox\nArgs: CODEWHALE_IMAGE, TOOLBOX_PACKAGES"]
    G --> H["Tag as CODEWHALE_TOOLBOX_IMAGE"]
    F -- Yes --> I["Use cached image"]
    H --> J["Start container"]
    I --> J
    J --> K["Mount: CODEWHALE_WORKSPACE → /workspace"]
    J --> L["Mount: CODEWHALE_HOME_VOLUME → /home/codewhale/.deepseek"]
    J --> M["Env: DEEPSEEK_API_KEY\n+ optional DEEPSEEK_BASE_URL / DEEPSEEK_NO_COLOR"]
    K & L & M --> N["Interactive CodeWhale session"]

Loading

_{Reviews (2): Last reviewed commit: "docs(docker): tighten toolbox compose de..." | Re-trigger Greptile}

[gemini-code-assist]

Code Review

This pull request introduces a Docker Compose toolbox template (docs/examples/compose.toolbox.yml) and documents its usage in docs/DOCKER.md. Feedback on the Compose file notes that the relative path for local CA certificates (./docker/certs) should be updated to ../../docker/certs to correctly resolve relative to the repository root rather than the Compose file's directory.

[gemini-code-assist]

In Docker Compose, relative host paths in bind mounts are resolved relative to the directory containing the Compose file. Since compose.toolbox.yml is located in docs/examples/, ./docker/certs will resolve to docs/examples/docker/certs instead of the repository root docker/certs. It should be updated to ../../docker/certs to correctly reference the repository root.

      # - ${CODEWHALE_CERTS_DIR:-../../docker/certs}:/usr/local/share/ca-certificates/local:ro