Skip to content

chore: drop Codespaces, document localhost + Docker step-by-step#195

Merged
fede-kamel merged 1 commit into
mainfrom
chore/remove-codespaces
May 15, 2026
Merged

chore: drop Codespaces, document localhost + Docker step-by-step#195
fede-kamel merged 1 commit into
mainfrom
chore/remove-codespaces

Conversation

@fede-kamel
Copy link
Copy Markdown
Contributor

Summary

Drop the Codespaces launch path. We're keeping two ways to run the workbench going forward — local from source and Docker — and the docs are reorganised around those two paths.

Codespaces never worked for the OCI providers (api-key or session token) because the OCI SDK signs every request with a private key on disk, and a fresh Codespace has neither ~/.oci/config nor any .pem. Trying to ship Codespaces alongside the OCI flow meant the demo path silently fell back to OpenAI / Anthropic only, which isn't representative of what locus is about.

Removed

  • .devcontainer/ (4 files — devcontainer.json, postCreate.sh, welcome.md, workbench-attach.sh).
  • Codespaces launch buttons, badges, billing copy from README.md, docs/index.md, docs/workbench.md.
  • The .app.github.dev allowedHost rule in workbench/web/vite.config.ts.

Doc updates

  • docs/workbench.md restructured into two clear sections:
    • Run it locally (from source) — prereqs (Python 3.11+, Node 20+), step-by-step git clonepip install → three-terminal setup, make-based shortcut, plus three curl commands to verify each tier is up.
    • Run it in Dockerdocker build + docker run, with both the OpenAI/Anthropic (no extra args) and OCI (-v "$HOME/.oci:$HOME/.oci:ro" -e "HOME=$HOME") variants explained. Includes a port-collision section for remapping host-side ports.
  • The Docker section explains why the OCI mount + HOME pair is needed: ~/.oci/config's key_file line is an absolute host path, so mirroring $HOME/.oci at the same path inside the container is what makes the SDK find the private key.
  • Provider settings entries updated — OCI providers now correctly state they work on both localhost and Docker (was "Local-machine only").
  • Troubleshooting calls out the two specific Docker+OCI failure modes: missing bind-mount and missing HOME env.
  • README.md collapsed to the same two paths, OCI bind-mount snippet matches.
  • workbench/README.md gains a ## Run in Docker section so the in-tree reader sees the same guidance.

Verified live

  • Built the workbench Docker image, ran with -v "$HOME/.oci:$HOME/.oci:ro" -e "HOME=$HOME"/api/models against LUIGI_FRA_API in us-chicago-1 returned 112 OCI models (the SDK successfully signed requests against the bind-mounted config + key file).
  • Confirmed the alternative dual-mount form (-v $HOME/.oci:/root/.oci:ro -v $HOME/.oci:$HOME/.oci:ro) also works, but the single-mount + HOME env form is cleaner.

Test plan

  • grep -ri codespace returns no matches across the tracked tree.
  • OCI bind-mount documented variant tested live against LUIGI_FRA_API (112 models returned).
  • CI green on this PR (lint, mypy, tests on 3.11–3.14, mkdocs strict build).

We ship two paths today — local from source and Docker — both end at
http://localhost:5173. Codespaces was the third option but the OCI
providers can't sign requests without ~/.oci/config and a private key
on disk, neither of which a Codespace has.

Removed:
- .devcontainer/ (devcontainer.json, postCreate.sh, welcome.md,
  workbench-attach.sh).
- Codespaces launch buttons / badges / billing copy from README,
  docs/index.md, docs/workbench.md.
- The `.app.github.dev` allowedHost rule in workbench/web/vite.config.ts.

Doc updates:
- docs/workbench.md is now organised as two clear paths: "Run it
  locally (from source)" and "Run it in Docker", each with prereqs,
  step-by-step commands, and a verification step.
- The Docker section documents the OCI bind-mount + HOME env trick.
  ~/.oci/config references the private key at an absolute host path,
  so mirroring $HOME/.oci at the same path inside the container (and
  pointing HOME at it) is what makes oci-apikey / oci-session work.
  Tested live: 112 OCI models returned via the bind-mounted config.
- README collapses to the same two paths and ships the same OCI
  bind-mount snippet.
- workbench/README.md gains a "Run in Docker" section so the in-tree
  audience sees the same guidance.
- Provider settings entries now state both hosting paths (was
  "Local-machine only").
- Troubleshooting calls out the two specific failure modes: "no
  profile" (missing bind-mount) and "key file missing" (HOME env
  not set).

workbench/web/src/main.ts: comment that referenced "On a Codespace"
now reads "On any non-localhost host" — same behaviour.

Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
@oracle-contributor-agreement oracle-contributor-agreement Bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label May 15, 2026
@fede-kamel fede-kamel merged commit 466c27c into main May 15, 2026
10 checks passed
@fede-kamel fede-kamel deleted the chore/remove-codespaces branch May 15, 2026 13:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

OCA Verified All contributors have signed the Oracle Contributor Agreement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant