build: BuildKit cache mounts + .dockerignore + cursor rule

Dockerfile opts into BuildKit (# syntax=docker/dockerfile:1.7) and mounts persistent caches at /root/.npm and /home/user/.cache/pip so npm and pip downloads survive across rebuilds. First build is unchanged; subsequent rebuilds skip the network for unchanged dependencies.

.dockerignore narrows the build context (drops .git, .cursor, node_modules, build outputs, Python/Node caches, .env files, backend/tests, etc.) so the daemon does not ship hundreds of MB of local-dev cruft to the builder on every build.

.cursor/rules/docker-build.mdc captures the conventions (syntax directive, cache mount targets, no --no-cache-dir, build context narrowing) so future agents reuse the same pattern instead of regressing.

Co-authored-by: Cursor <cursoragent@cursor.com>

.cursor/rules/docker-build.mdc

@@ -0,0 +1,87 @@
+---
+description: Docker build cache conventions for CCAI-Vibe-Demo
+globs: Dockerfile,docker-compose*.yml,.dockerignore,backend/requirements.txt,frontend/package*.json
+alwaysApply: false
+---
+
+# Docker build cache conventions
+
+This project uses **BuildKit cache mounts** so `npm ci` and `pip install`
+skip the network when only source files change. Don't replace them
+with plain `RUN` commands - that reintroduces full re-downloads on every
+dependency change.
+
+## Required Dockerfile pattern
+
+The Dockerfile MUST start with the BuildKit syntax directive:
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+```
+
+### Frontend stage (root user, node:22-alpine)
+
+```dockerfile
+COPY frontend/package.json frontend/package-lock.json ./
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci
+```
+
+### Backend stage (USER user, uid 1000, python:3.12-slim)
+
+```dockerfile
+COPY --chown=user backend/requirements.txt ./
+RUN --mount=type=cache,target=/home/user/.cache/pip,uid=1000,gid=1000 \
+    pip install --user -r requirements.txt
+```
+
+The `uid=1000,gid=1000` flags are mandatory because the cache target
+sits inside the unprivileged user's home dir. Without them the cache
+is created root-owned and pip cannot write to it.
+
+## Don'ts
+
+- **Don't** pass `--no-cache-dir` to `pip install`. It defeats the
+  cache mount. The mount lives outside the image, so wheels never
+  bloat the final layer either way.
+- **Don't** `COPY .` blindly. Layers must be copy-deps-first,
+  copy-source-second so a source edit doesn't bust the deps layer.
+- **Don't** add new files outside `backend/`, `frontend/` or the
+  lockfiles to a `COPY` line without first checking `.dockerignore`.
+
+## Build context (`.dockerignore`)
+
+The ignore list excludes `.git/`, `node_modules/`, `frontend/build/`,
+`agent-transcripts/`, `__pycache__`, secrets (`.env*`),
+`docker-compose.override.yml`, `backend/tests/`, and editor metadata.
+If you need a previously-ignored path inside the image, add a narrow
+`!path/to/keep` exception rather than removing the broad ignore.
+
+## Verifying the cache works
+
+After a Dockerfile or deps-file change, run two builds back to back:
+
+```powershell
+docker compose build
+docker compose build  # second time
+```
+
+The second build's `npm ci` / `pip install` step should print a
+`CACHED` line (when nothing in the deps file changed) or a
+near-instant `=> [internal] load build context` finish (when only
+source files changed). If it re-downloads, the cache mount is
+mis-configured.
+
+If a build ever errors with `the --mount option requires BuildKit`,
+opt in explicitly:
+
+```powershell
+$env:DOCKER_BUILDKIT=1; docker compose build
+```
+
+## HuggingFace Spaces compatibility
+
+HuggingFace's Docker Space builder honors the `# syntax=` directive
+and BuildKit cache mounts. Older builders silently treat the mounts
+as no-ops, so this Dockerfile remains forward-compatible with any
+plain-Docker environment.

.dockerignore

@@ -0,0 +1,61 @@
+# Build context exclusions for `docker build` / `docker compose build`.
+# Trimming the context speeds the daemon transfer and keeps cache hashes
+# stable: changes to ignored paths do NOT invalidate Dockerfile layers.
+
+# ── Git / VCS metadata ───────────────────────────────────────────────
+.git
+.gitignore
+.gitattributes
+.github
+
+# ── Cursor / agent transcripts (local IDE state, never needed in image)
+.cursor
+agent-transcripts
+.commit-msg.txt
+
+# ── Editor / OS junk ─────────────────────────────────────────────────
+.vscode
+.idea
+.DS_Store
+Thumbs.db
+*.swp
+
+# ── Secrets / env (image gets env at runtime via docker-compose)
+.env
+.env.*
+*.env
+!**/.env.example
+
+# ── Python local caches ──────────────────────────────────────────────
+**/__pycache__
+*.pyc
+*.pyo
+*.pyd
+*.egg-info
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.venv
+venv
+
+# ── Node local caches & build outputs ────────────────────────────────
+# Lockfiles ARE included on purpose so `npm ci` is reproducible.
+**/node_modules
+frontend/build
+frontend/.next
+frontend/.cache
+**/.cache
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# ── Local-only docker compose overrides ──────────────────────────────
+# The base docker-compose.yml is needed for `docker compose build` from
+# the build dir, but the local override (which references absolute host
+# paths to a secrets file outside this repo) shouldn't end up in the
+# image build context.
+docker-compose.override.yml
+
+# ── Tests aren't shipped in the runtime image ────────────────────────
+# (Re-enable if you want to run pytest inside the deployed container.)
+backend/tests

Dockerfile

@@ -1,11 +1,29 @@
+# syntax=docker/dockerfile:1.7
+#
+# BuildKit cache mounts speed up rebuilds by persisting npm and pip
+# package caches across builds (outside the image - they don't bloat
+# the final layer). The first `docker compose build` is unchanged;
+# subsequent rebuilds skip the network for any unchanged dependency.
+#
+# The `# syntax=` directive auto-opts into BuildKit on Docker Desktop
+# 20.10+; HuggingFace Spaces also supports this directive. Older
+# builders silently treat the cache mounts as no-ops, so this file
+# remains forward-compatible.
+
 FROM node:22-alpine AS frontend-build
 WORKDIR /app/frontend
+
+# Copy lockfile + manifest first so the layer hash only changes when
+# deps actually change, not on every source edit.
 COPY frontend/package.json frontend/package-lock.json ./
-RUN npm ci
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci
+
 COPY frontend/ ./
 ENV REACT_APP_API_URL=
 RUN npm run build
 
+
 FROM python:3.12-slim
 
 RUN useradd -m -u 1000 user
@@ -16,8 +34,11 @@ ENV HOME=/home/user \
 
 WORKDIR $HOME/app
 
+# Lockfile-equivalent first; cache mount targets the unprivileged
+# user's pip cache (uid/gid 1000 matches the `user` account).
 COPY --chown=user backend/requirements.txt ./
-RUN pip install --no-cache-dir -r requirements.txt
+RUN --mount=type=cache,target=/home/user/.cache/pip,uid=1000,gid=1000 \
+    pip install --user -r requirements.txt
 
 COPY --chown=user backend/ ./
 COPY --chown=user --from=frontend-build /app/frontend/build ./static