feat: Add Dockerfile for snapshot source (ENG-3240) (#4331)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

This PR implements Phase 1 of the snapshot source Docker image support,
enabling the snapshot source to run as a container in the benchmark
environment.

## Changes

- **Created `sources/snapshot/build/package/Dockerfile`**: Follows the
established pattern from GCP and Azure sources with multi-stage build
- **Updated `build/images-bake.hcl`**: Added "snapshot" to the source
matrix, enabling CI builds
- **Updated `sources/snapshot/README.md`**: Added comprehensive Docker
usage documentation with build and run examples
- **Updated `docs/ARCHITECTURE.md`**: Added snapshot-source to the
components list
- **Fixed `.dockerignore`**: Added exception to include
`docs.overmind.tech/docs/sources/` in Docker build context

## CI Fix

The initial commit had a Docker build failure because `.dockerignore`
was excluding the entire `docs.overmind.tech/` directory. The snapshot
source needs access to `docs.overmind.tech/docs/sources/` which contains
embedded adapter catalog data (JSON files with metadata like category,
descriptive names, etc.).

**Solution**: Modified `.dockerignore` to add an exception using
`!docs.overmind.tech/docs/sources/` to allow this directory to be
included in the Docker build context while still excluding the rest of
`docs.overmind.tech/`.

## Validation

All validation criteria from the implementation plan have been met:

✅ **Dockerfile builds successfully**
- Verified the Dockerfile follows the same pattern as `sources/gcp` and
`sources/azure`
- Docker build now succeeds with catalog data properly embedded
- Multi-stage build produces a minimal alpine-based runtime image

✅ **Binary runs with required environment variables**
- Tested with `SNAPSHOT_SOURCE=/data/snapshot.json` environment variable
- Verified NATS connection configuration works (requires
`OVERMIND_MANAGED_SOURCE=true` with `NATS_SERVICE_HOST` and
`NATS_SERVICE_PORT` for local NATS, or uses production NATS URL for
cloud deployments)
- Confirmed snapshot loading from test data file

✅ **Health check endpoint responds**
- Tested `/healthz/alive` and `/healthz/ready` endpoints
- Endpoints respond correctly on the configured port (default 8089,
configurable via `--health-check-port`)
- Returns appropriate status messages based on NATS connection and
adapter initialization state

✅ **Image appears in CI build matrix**
- Added to the `source` target matrix in `build/images-bake.hcl`
- Will be built automatically on push to main alongside azure-source and
gcp-source
- Tagged as `ghcr.io/overmindtech/workspace/snapshot-source:${TAG}`

✅ **Tests pass**
- All snapshot adapter unit tests pass
- Adapter metadata correctly sourced from embedded catalog

✅ **CI builds pass**
- All 46 CI jobs passing including Docker build

## Testing

```bash
# Build the binary
go build -o snapshot-source sources/snapshot/main.go

# Run with test snapshot
ALLOW_UNAUTHENTICATED=true \
SNAPSHOT_SOURCE=/workspace/services/api-server/service/changeanalysis/testdata/snapshot.json \
./snapshot-source --health-check-port=9999

# Test health checks
curl http://localhost:9999/healthz/alive
curl http://localhost:9999/healthz/ready

# Run tests
cd sources/snapshot/adapters && go test -v
```

## Docker Usage

```bash
# Build the image
docker buildx bake snapshot-source

# Run the container
docker run --rm \
  -v /path/to/snapshot.json:/data/snapshot.json:ro \
  -e SNAPSHOT_SOURCE=/data/snapshot.json \
  -e NATS_SERVICE_HOST=nats \
  -e NATS_SERVICE_PORT=4222 \
  -e OVERMIND_MANAGED_SOURCE=true \
  -e ALLOW_UNAUTHENTICATED=true \
  ghcr.io/overmindtech/workspace/snapshot-source:dev
```

## Related Issues

- Closes ENG-3240
- Part of the "Improve local feedback cycles" project for LLM-based v6
change analysis benchmarking

Linear Issue:
[ENG-3240](https://linear.app/overmind/issue/ENG-3240/phase-1-snapshot-source-docker-image)
<!-- CURSOR_AGENT_PR_BODY_END -->

Linear Issue:
[ENG-3240](https://linear.app/overmind/issue/ENG-3240/phase-1-snapshot-source-docker-image)

<div><a
href="https://cursor.com/agents/bc-18a45891-db10-44db-8523-bf9556848e40"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-18a45891-db10-44db-8523-bf9556848e40"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: carabasdaniel <carabasdaniel@users.noreply.github.com>
GitOrigin-RevId: e55b0de25a597ca8e813d7be3003f27de06ce2be

Author: 2 people

sources/snapshot/README.md

@@ -37,6 +37,91 @@ The snapshot source requires a snapshot file or URL to be specified:
 --health-check-port <port>        # Health check port (default: 8089)
 ```
 
+### Running with Docker
+
+#### Build the Docker image
+
+Build the snapshot source Docker image:
+
+```bash
+docker buildx bake snapshot
+```
+
+Or build directly with docker build:
+
+```bash
+docker build -f sources/snapshot/build/package/Dockerfile \
+  --build-arg BUILD_VERSION=dev \
+  --build-arg BUILD_COMMIT=$(git rev-parse HEAD) \
+  -t snapshot-source:local .
+```
+
+#### Run the Docker container
+
+Run the container with a mounted snapshot file:
+
+**Local/dev environment (unauthenticated):**
+
+```bash
+docker run --rm \
+  -v /path/to/snapshot.json:/data/snapshot.json:ro \
+  -e SNAPSHOT_SOURCE=/data/snapshot.json \
+  -e OVERMIND_MANAGED_SOURCE=true \
+  -e NATS_SERVICE_HOST=nats \
+  -e NATS_SERVICE_PORT=4222 \
+  -e ALLOW_UNAUTHENTICATED=true \
+  --network=host \
+  ghcr.io/overmindtech/workspace/snapshot-source:dev
+```
+
+> ⚠️ **WARNING**: `ALLOW_UNAUTHENTICATED=true` is for local/dev testing only. Do not use in production.
+
+**Production environment (authenticated):**
+
+```bash
+docker run --rm \
+  -v /path/to/snapshot.json:/data/snapshot.json:ro \
+  -e SNAPSHOT_SOURCE=/data/snapshot.json \
+  -e OVERMIND_MANAGED_SOURCE=true \
+  -e API_KEY=your-api-key \
+  -e NATS_SERVICE_HOST=nats \
+  -e NATS_SERVICE_PORT=4222 \
+  --network=host \
+  ghcr.io/overmindtech/workspace/snapshot-source:dev
+```
+
+Or use with docker-compose (local/dev):
+
+```yaml
+services:
+  snapshot-source:
+    image: ghcr.io/overmindtech/workspace/snapshot-source:dev
+    volumes:
+      - ./snapshot.json:/data/snapshot.json:ro
+    environment:
+      SNAPSHOT_SOURCE: /data/snapshot.json
+      OVERMIND_MANAGED_SOURCE: "true"
+      NATS_SERVICE_HOST: nats
+      NATS_SERVICE_PORT: 4222
+      ALLOW_UNAUTHENTICATED: "true"  # WARNING: local/dev only
+    depends_on:
+      - nats
+```
+
+For production, replace `ALLOW_UNAUTHENTICATED: "true"` with `API_KEY: ${API_KEY}` and set the API key via environment variable or secrets management.
+
+#### Health check
+
+The container exposes health check endpoints on port 8089:
+
+```bash
+# Liveness probe - checks NATS connection
+curl http://localhost:8089/healthz/alive
+
+# Readiness probe - checks adapter initialization
+curl http://localhost:8089/healthz/ready
+```
+
 ### Running Locally
 
 #### Option 1: With backend services (recommended)

sources/snapshot/build/package/Dockerfile

@@ -0,0 +1,26 @@
+# Build the source binary
+FROM golang:1.26-alpine AS builder
+ARG TARGETOS
+ARG TARGETARCH
+ARG BUILD_VERSION
+ARG BUILD_COMMIT
+
+# required for generating the version descriptor
+RUN apk upgrade --no-cache && apk add --no-cache git
+
+WORKDIR /workspace
+
+# Copy the go source
+COPY . .
+
+# Build
+RUN --mount=type=cache,target=/go/pkg \
+    --mount=type=cache,target=/root/.cache/go-build \
+    GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -trimpath -ldflags="-s -w -X github.com/overmindtech/cli/go/tracing.version=${BUILD_VERSION} -X github.com/overmindtech/cli/go/tracing.commit=${BUILD_COMMIT}" -o source sources/snapshot/main.go
+
+FROM alpine:3.23.3
+WORKDIR /
+COPY --from=builder /workspace/source .
+USER 65534:65534
+
+ENTRYPOINT ["/source"]