Address CodeRabbit review feedback across Helm chart, docs, and entrypoint

- Fix Neo4j service name in _helpers.tpl (use Release.Name, not Release.Name-neo4j)
- Add service-mode-aware container port helper and health check probes
- Align ANTHROPIC_API_KEY env condition with secret template
- Add REQUIRED comment for Neo4j password in values.yaml
- Remove Chart.lock from .gitignore to pin subchart versions
- Make configuration docs service-aware with per-service required vars
- Add POSTGRES_URL to Docker all-in-one example
- Add json language identifiers to code fences in blueprints docs
- Fix grammar in blueprints docs
- Document ui service in IMBI_SERVICE table
- Quote printf argument in entrypoint.sh
- Change docs-serve port to 8088 to avoid conflict with API

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gmr

.gitignore

@@ -7,4 +7,3 @@ build/
 dist/
 docs/site/
 helm/imbi/charts/
-helm/imbi/Chart.lock

docs/docs/admin/blueprints.md

@@ -11,7 +11,7 @@ project's metadata is validated against the blueprint's schema.
 
 ## Creating a Blueprint
 
-```
+```json
 POST /api/blueprints
 {
   "name": "Microservice",
@@ -40,7 +40,7 @@ POST /api/blueprints
 
 When creating a project, specify the blueprint to apply its schema:
 
-```
+```json
 POST /api/projects
 {
   "name": "my-service",
@@ -60,5 +60,5 @@ are invalid.
 ## Updating Blueprints
 
 Blueprint schemas can be updated over time. Existing projects are not
-retroactively validated against updated schemas, but new creates and
-updates will use the current schema.
+retroactively validated against updated schemas, but new project
+creations and updates will use the current schema.

docs/docs/deployment/docker.md

@@ -12,6 +12,7 @@ By default, the container starts all services behind a Caddy reverse proxy:
 docker run -p 8080:8080 \
   -e NEO4J_URL=bolt://neo4j:7687 \
   -e CLICKHOUSE_URL=http://default:password@clickhouse:8123/imbi \
+  -e POSTGRES_URL=postgresql://user:pass@postgres/imbi \
   -e IMBI_AUTH_JWT_SECRET=your-secret \
   -e IMBI_AUTH_ENCRYPTION_KEY=your-key \
   ghcr.io/aweber-imbi/imbi:latest

docs/docs/getting-started/configuration.md

@@ -5,15 +5,35 @@ own set of variables from the shared environment.
 
 ## Required Variables
 
-These must be set for Imbi to start:
+Which variables are required depends on the service being run
+(see `IMBI_SERVICE` below). When running `IMBI_SERVICE=all` (the default),
+all service-specific variables are required.
+
+### Core (all services)
 
 | Variable | Description |
 |----------|-------------|
-| `NEO4J_URL` | Neo4j Bolt connection URL (e.g. `bolt://neo4j:7687`) |
-| `CLICKHOUSE_URL` | ClickHouse HTTP connection URL (e.g. `http://default:password@clickhouse:8123/imbi`) |
 | `IMBI_AUTH_JWT_SECRET` | Secret key for signing JWT tokens. Use a random string of at least 32 characters. |
 | `IMBI_AUTH_ENCRYPTION_KEY` | Fernet encryption key for encrypting sensitive data at rest. |
 
+### API and Assistant
+
+| Variable | Description |
+|----------|-------------|
+| `NEO4J_URL` | Neo4j Bolt connection URL (e.g. `bolt://neo4j:7687`) |
+
+### API only
+
+| Variable | Description |
+|----------|-------------|
+| `CLICKHOUSE_URL` | ClickHouse HTTP connection URL (e.g. `http://default:password@clickhouse:8123/imbi`) |
+
+### Gateway
+
+| Variable | Description |
+|----------|-------------|
+| `POSTGRES_URL` | PostgreSQL connection URL (e.g. `postgresql://user:pass@host/db`) |
+
 ## Neo4j
 
 | Variable | Description | Default |
@@ -104,4 +124,4 @@ When running the Docker image, you can select which service to run:
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `IMBI_SERVICE` | Service to run: `all`, `api`, `assistant`, `gateway`, `mcp` | `all` |
+| `IMBI_SERVICE` | Service to run: `all`, `api`, `assistant`, `gateway`, `mcp`, `ui` | `all` |

entrypoint.sh

@@ -39,7 +39,7 @@ require_gateway_vars() {
 check_errors() {
     if [ -n "$errors" ]; then
         echo "ERROR: Missing required environment variables for $1:" >&2
-        printf "$errors" >&2
+        printf '%b' "$errors" >&2
         echo "" >&2
         echo "Set the variables above and try again." >&2
         exit 1

helm/imbi/templates/_helpers.tpl

@@ -37,7 +37,7 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 
 {{- define "imbi.neo4jUrl" -}}
 {{- if .Values.neo4j.enabled }}
-{{- printf "bolt://%s-neo4j:7687" .Release.Name }}
+{{- printf "bolt://%s:7687" .Release.Name }}
 {{- else }}
 {{- .Values.externalNeo4j.url }}
 {{- end }}
@@ -51,6 +51,15 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 {{- end }}
 {{- end }}
 
+{{- define "imbi.containerPort" -}}
+{{- if eq .Values.service.mode "api" }}8000
+{{- else if eq .Values.service.mode "mcp" }}8001
+{{- else if eq .Values.service.mode "assistant" }}8002
+{{- else if eq .Values.service.mode "gateway" }}8003
+{{- else }}8080
+{{- end }}
+{{- end }}
+
 {{- define "imbi.postgresUrl" -}}
 {{- if .Values.postgresql.enabled }}
 {{- printf "postgresql://postgres:%s@%s-postgresql/%s" .Values.postgresql.auth.postgresPassword .Release.Name .Values.postgresql.auth.database }}

helm/imbi/templates/deployment.yaml

@@ -20,7 +20,7 @@ spec:
           imagePullPolicy: {{ .Values.image.pullPolicy }}
           ports:
             - name: http
-              containerPort: 8080
+              containerPort: {{ include "imbi.containerPort" . | trim }}
               protocol: TCP
           envFrom:
             - configMapRef:
@@ -53,7 +53,7 @@ spec:
                 secretKeyRef:
                   name: {{ include "imbi.secretName" . }}
                   key: postgres-url
-            {{- if .Values.assistant.enabled }}
+            {{- if and .Values.assistant.enabled .Values.assistant.anthropicApiKey }}
             - name: ANTHROPIC_API_KEY
               valueFrom:
                 secretKeyRef:
@@ -72,6 +72,7 @@ spec:
                   name: {{ include "imbi.secretName" . }}
                   key: s3-secret-key
             {{- end }}
+          {{- if eq .Values.service.mode "all" }}
           livenessProbe:
             httpGet:
               path: /api/status
@@ -84,5 +85,30 @@ spec:
               port: http
             initialDelaySeconds: 5
             periodSeconds: 10
+          {{- else if eq .Values.service.mode "api" }}
+          livenessProbe:
+            httpGet:
+              path: /status
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 15
+          readinessProbe:
+            httpGet:
+              path: /status
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          {{- else }}
+          livenessProbe:
+            tcpSocket:
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 15
+          readinessProbe:
+            tcpSocket:
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          {{- end }}
           resources:
             {{- toYaml .Values.resources | nindent 12 }}

helm/imbi/values.yaml

@@ -50,7 +50,7 @@ neo4j:
   neo4j:
     edition: community
     acceptLicenseAgreement: "yes"
-    password: ""
+    password: ""  # REQUIRED: must be overridden with a secure password
 
 # External Neo4j (when neo4j.enabled is false)
 externalNeo4j:

justfile

@@ -41,7 +41,7 @@ docs:
 [doc("Serve documentation locally for development")]
 [group("Docs")]
 docs-serve:
-    docker run --rm -p 8000:8000 -v {{ justfile_directory() }}/docs:/docs squidfunk/mkdocs-material
+    docker run --rm -p 8088:8000 -v {{ justfile_directory() }}/docs:/docs squidfunk/mkdocs-material
 
 [doc("Remove build artifacts")]
 [group("Build")]