Palette content index

Palette content index

The homepage search bar and global cmd+K palette query a prebuilt SQLite index (palette.db) produced from the repository content/ tree. The index is a backend artefact: Go serves POST /api/palette/query; it is not bundled as a Next.js static file.

Canonical paths

Context	Path
Local / CI build output	backend/dist/palette.db
Baked into Docker images	/app/palette.db
Runtime configuration	SHOWCASE_PALETTE_DB=/app/palette.db

Build the index locally:

cd backend
go run ./cmd/palette-indexer -content ../content -out ./dist/palette.db

The indexer resolves spec-assertion artefacts (requirement explainers under content/assertions/) against the conformance registry. -registry defaults to internal/conformance/vc-requirements.yaml relative to backend/; pass it explicitly when running from elsewhere. An explainer whose ID is not in the registry fails the build.

Baked into the image (recommended)

docker/Dockerfile.backend and docker/Dockerfile.fly compile palette-indexer, run it against /content with -registry /app/internal/conformance/vc-requirements.yaml at image build time, copy /app/palette.db into the runtime layer, and set SHOWCASE_PALETTE_DB=/app/palette.db.

Implication: changing content/ or the registry requires rebuilding the backend (or monolith) image even when no Go source changed.

Verify after deploy:

curl -s https://your-host/health | jq '.palette'
curl -s https://your-host/api | jq '.endpoints.palette'
curl -sf -X POST https://your-host/api/palette/query \
  -H 'content-type: application/json' \
  -d '{"q":"pkce"}' | jq '.results | length'

In SHOWCASE_ENV=production, the server refuses to start if SHOWCASE_PALETTE_DB is unset or the file cannot be opened.

Mounted as a volume (self-hosted)

For custom monolith deployments, build the index on a host or in CI and mount it at the canonical path:

services:
  backend:
    image: ghcr.io/parlesec/protocolsoup-federation:latest
    environment:
      SHOWCASE_ENV: production
      SHOWCASE_PALETTE_DB: /app/palette.db
    volumes:
      - ./backend/dist/palette.db:/app/palette.db:ro

Rebuild the index whenever content/ changes, then restart the backend.

Related

• Deployment models — Model 3 (simple monolith) includes the baked index via Dockerfile.backend
• Environment variables — SHOWCASE_PALETTE_DB
• Contributor guide: palette section in the repository CONTRIBUTING.md