feat: Implement environment validation with Docker labels

- Add enhanced Docker labels with JSON metadata for runtime and CI/CD variables
- Create env-validator.py for cross-file consistency checking
- Add runtime validation to start.sh
- Fix deploy-app-runner.sh to only pass runtime variables (remove MXCP_DATA_*)
- Add validation steps to both GitHub workflows
- Update README.md with self-documenting environment approach
- Delete redundant ENVIRONMENT.md.template
- Add validate-env task to justfile with critical path dependencies

This provides clear separation between CI/CD and runtime secrets, with automatic validation to catch configuration errors early.

Author: ppolydoras

.github/scripts/deploy-app-runner.sh

@@ -49,11 +49,11 @@ echo "CPU: $CPU_SIZE"
 echo "Memory: $MEMORY_SIZE"
 
 # Build runtime environment variables JSON
-# Start with basic vars
+# Only include variables meant for runtime, NOT CI/CD secrets
 RUNTIME_ENV_JSON='{"PORT": "8000", "PYTHONUNBUFFERED": "1"'
 
-# Add any API keys that are set
-for var in OPENAI_API_KEY ANTHROPIC_API_KEY VERTEC_API_KEY MXCP_DATA_ACCESS_KEY_ID MXCP_DATA_SECRET_ACCESS_KEY; do
+# Add only runtime API keys (exclude MXCP_DATA_* which are CI/CD only)
+for var in OPENAI_API_KEY ANTHROPIC_API_KEY VERTEC_API_KEY; do
     if [ -n "${!var}" ]; then
         # Escape the value for JSON
         ESCAPED_VALUE=$(echo "${!var}" | sed 's/"/\\"/g')

.github/workflows/deploy.yml

@@ -104,6 +104,11 @@ jobs:
         echo "📝 Validating YAML configurations..."
         python -c "import yaml; yaml.safe_load(open('mxcp-site.yml')); print('✅ mxcp-site.yml is valid')"
         python -c "import yaml, glob; [yaml.safe_load(open(f)) for f in glob.glob('tools/*.yml')]; print('✅ All tool configurations valid')"
+    
+    - name: Validate environment consistency
+      run: |
+        echo "🔍 Checking environment variable consistency..."
+        python deployment/env-validator.py
         echo "✅ Pre-flight checks passed"
 
   deploy:

.squirro/workflows/build-and-push-to-ecr.yml.template

@@ -93,6 +93,11 @@ jobs:
     - name: Run configuration validation
       run: |
         just validate-config
+    
+    - name: Validate environment consistency
+      run: |
+        echo "🔍 Checking environment variable consistency..."
+        python deployment/env-validator.py
 
   build-and-push:
     needs: [check-secrets, validate-config]

ENVIRONMENT.md.template

@@ -1022,13 +1022,59 @@ gh secret set OPENAI_API_KEY --body "sk-..."
 gh secret set AWS_ACCESS_KEY_ID --body "AKIA..."
 ```
 
+## Environment Variables
+
+This project uses a self-documenting approach for environment variables through Docker labels.
+
+### Discovering Requirements
+
+```bash
+# List all runtime variables (passed to container)
+docker inspect your-image:latest | jq -r '
+  .[] | .Config.Labels | to_entries[] | 
+  select(.key | startswith("env.runtime")) | 
+  .key + " = " + .value'
+
+# List all CI/CD variables (used during deployment)
+docker inspect your-image:latest | jq -r '
+  .[] | .Config.Labels | to_entries[] | 
+  select(.key | startswith("env.cicd")) | 
+  .key + " = " + .value'
+
+# Parse the JSON metadata for a specific variable
+docker inspect your-image:latest | jq -r '
+  .[] | .Config.Labels."env.runtime.OPENAI_API_KEY" | fromjson'
+```
+
+### Setting Up Your Project
+
+1. **GitHub Secrets** (for CI/CD):
+   - `AWS_ACCESS_KEY_ID` (required)
+   - `AWS_SECRET_ACCESS_KEY` (required) 
+   - `MXCP_DATA_ACCESS_KEY_ID` (optional - for S3 data)
+   - `MXCP_DATA_SECRET_ACCESS_KEY` (optional - for S3 data)
+
+2. **Runtime Secrets** (automatically passed to App Runner):
+   - `OPENAI_API_KEY` (required)
+   - `ANTHROPIC_API_KEY` (optional)
+   - `VERTEC_API_KEY` (optional - API projects)
+
+3. **GitHub Variables** (non-sensitive config):
+   - `AWS_REGION`, `ECR_REPOSITORY`, etc. (see config.env.template)
+
+### Important Notes
+
+- CI/CD secrets (AWS_*) are NEVER passed to the running container
+- Runtime secrets are injected by App Runner, not baked into the image
+- Run `python deployment/env-validator.py` to check consistency
+
 ## What's Included vs What's Not
 
 ### ✅ What This Template Provides
 
 - **Health Check**: Basic `/health` endpoint for App Runner monitoring
-- **Logging**: stdout/stderr captured by AWS App Runner (viewable in CloudWatch)
-- **Configuration**: Secure management of API keys and settings
+- **Environment Validation**: Runtime checks and consistency validation
+- **Configuration**: Secure management via config.env + GitHub Secrets
 - **Testing**: 4-tier testing framework (data → tools → API → LLM)
 - **CI/CD**: Automated deployment pipeline
 

README.md

@@ -20,6 +20,17 @@ RUN groupadd -r mxcp && useradd -r -g mxcp -m -d /home/mxcp mxcp
 COPY requirements.txt ./requirements.txt
 RUN pip install --no-cache-dir -r requirements.txt
 
+# Document runtime environment variables (injected by App Runner)
+LABEL env.runtime.OPENAI_API_KEY='{"required": true, "type": "secret", "description": "OpenAI API key for LLM calls", "example": "sk-..."}'
+LABEL env.runtime.ANTHROPIC_API_KEY='{"required": false, "type": "secret", "description": "Anthropic API key for Claude models", "example": "sk-ant-..."}'
+LABEL env.runtime.VERTEC_API_KEY='{"required": false, "type": "secret", "description": "Vertec API key (API projects only)", "example": "vtc_..."}'
+
+# Document CI/CD environment variables (used during deployment only)
+LABEL env.cicd.AWS_ACCESS_KEY_ID='{"required": true, "type": "secret", "description": "AWS access key for deployment", "example": "AKIA..."}'
+LABEL env.cicd.AWS_SECRET_ACCESS_KEY='{"required": true, "type": "secret", "description": "AWS secret key for deployment", "example": "..."}'
+LABEL env.cicd.MXCP_DATA_ACCESS_KEY_ID='{"required": false, "type": "secret", "description": "AWS key for S3 data download", "example": "AKIA..."}'
+LABEL env.cicd.MXCP_DATA_SECRET_ACCESS_KEY='{"required": false, "type": "secret", "description": "AWS secret for S3 data download", "example": "..."}'
+
 # Copy the entire project
 COPY . .