Last updated: Sep 1, 2025, 01:10 PM UTC

Build & Release Overview (Simple)

This is a quick, practical guide to how builds work now that the UI lives in‑repo under claudecodeui/ (no submodules).

What You Need To Know

  • UI + Server live in claudecodeui/.
  • Local dev uses Vite for UI and Node for server.
  • Docker dev runs a production‑like container on :3006.
  • GitHub Actions builds and publishes Docker images to GHCR on pushes to main.
  • The VERSION file controls release tags.

Local Development

  • Full dev (UI + server):
    • ./dev.sh → runs on http://localhost:3007
  • UI only:
    • cd claudecodeui && npm ci && npm run dev (Node v20)
  • Build UI:
    • cd claudecodeui && npm run build

Docker Development (Production‑like)

  • Build + run container locally:
    • ./docker-dev.sh → http://localhost:3006
  • Useful for validating Docker behavior, file mounts, and envs.

CI Builds (GitHub Actions)

  • Two workflows:
    • ci.yml (UI + Docs build on push/PR)
    • docker-build.yml (Docker image build/publish on pushes to main)
  • Triggers for Docker image:
    • Changes in claudecodeui/**
    • Changes in claudecodeui/Dockerfile.sliplane
    • Changes in VERSION
    • Manual trigger via the Actions tab (workflow_dispatch)

Release Flow (GHCR)

  • Bump version and push to main:
    • ./docker-build-ghcr.sh (from a clean working tree)
    • Script will: switch to main, fast‑forward, bump VERSION, commit, push.
  • Image published to: ghcr.io/wapdat/sasha-ai-knowledge-management
  • Tags include: latest, vX.Y.Z, X.Y.Z

Where Things Live

  • UI + Server: claudecodeui/
  • Main Dockerfile: claudecodeui/Dockerfile.sliplane
  • Docs source: docs/ → built artifacts in html/ and html-static/
  • Shared docs data (at runtime): /home/nodejs/all-project-files/docs (inside Docker)

Troubleshooting (Quick)

  • Script says “non‑fast‑forward” when pushing:
    • Pull latest main (fast‑forward), then re‑run ./docker-build-ghcr.sh.
  • Nothing builds after push:
    • Confirm you pushed to main and changed one of the trigger paths.
    • Or run the workflow manually from GitHub Actions.
  • UI build fails in CI:
    • Ensure Node v20 is used locally; run npm ci && npm run build in claudecodeui/.