Add Helm deployment documentation with common scenarios

[Copilot]

Helm Chart Documentation Enhancement - COMPLETE ✅

• Review existing Helm chart documentation (README.md and EXAMPLES.md)
• Create docs/deployment/helm.md with overview and quick start scenarios
• Update docs/deployment/index.md to include Helm deployment option
• Verify all deployment scenarios are documented
• Address review feedback on security and documentation links
• Fix critical issues from thorough line-by-line review

---

Changes Summary

Initial Documentation (Commits 1-2)

• Created comprehensive docs/deployment/helm.md (379 lines)
• Updated docs/deployment/index.md with Helm deployment section
• All deployment scenarios documented: SQLite, PostgreSQL, Redis, Ingress, Autoscaling

Review Feedback Addressed (Commit 3)

Security Improvements:

• Changed DATABASE_URL examples from user:pass to USER:PASSWORD (uppercase placeholders)
• Changed sslmode=require to sslmode=verify-full for better certificate verification
• Added warning comments: "NOTE: Replace USER and PASSWORD with your actual DB credentials; never commit real secrets"
• Updated Redis password generation from placeholder text to openssl rand -base64 32

Documentation Links Fixed:

• Updated ../configuration.md → ../getting-started/configuration.md
• Updated ../token-management.md → ../guides/token-management.md

Critical Issues Fixed (Commit 4)

Markdown Formatting:

• Fixed leading space before bullet in docs/deployment/index.md line 78

Dispatcher Example (Critical Fix):

• Added missing kubectl create secret command showing how to create the dispatcher API key secret
• Added explicit --set dispatcher.apiKey.existingSecret.key="DISPATCHER_API_KEY" to prevent silent failures
• Users now have complete working example with correct key names

PostgreSQL Build Requirements:

• Added note to index.md PostgreSQL quick start about custom image build requirements
• Softened wording in helm.md from "Ensure your Docker image" to "If building images yourself"
• Clarified that pre-built images from ghcr.io include PostgreSQL support by default

OCI vs Local Path:

• Added prominent callout at start of Quick Start Scenarios explaining local path vs OCI registry choice
• Helps users understand when to use deploy/helm/llm-proxy vs oci://ghcr.io/sofatutor/llm-proxy

Minor Improvements:

• Removed hard-coded "Last Updated" date that would create maintenance burden

All review comments from thorough line-by-line review have been addressed.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[deploy/helm] Helm chart documentation: SQLite vs Postgres, ingress, autoscaling, common scenarios</issue_title>
<issue_description>## Summary
Add concise Helm chart documentation covering the common deployment scenarios without turning it into a giant “platform guide”.

This is explicitly not Kubernetes provisioning / CI/CD / GitOps.

Scope

• Document minimal install (single-replica, SQLite) with helm install example
• Document external PostgreSQL scenario (references to existing Secret for DATABASE_URL)
• Document external Redis scenario (values + env wiring)
• Document optional ingress + autoscaling usage (once implemented in [deploy/helm] Ingress + autoscaling hardening (HPA) for llm-proxy #207)
• Keep examples short; prefer copy-pastable helm install ... --set ... or small values.yaml snippets

Where

• Prefer a chart-local README (e.g. deploy/helm/llm-proxy/README.md) and/or a short pointer from docs/deployment/index.md.

Dependencies

• Depends on [deploy/helm] Secure secrets injection: MANAGEMENT_TOKEN + DATABASE_URL (external Postgres) #203/[deploy/helm] External Redis support (event bus + cache) and optional in-cluster Redis toggle #204/[deploy/helm] Ingress + autoscaling hardening (HPA) for llm-proxy #207 for the specific values keys.

Acceptance Criteria

• Users can deploy:
  • SQLite mode
  • External Postgres mode
  • External Redis mode
  • (When available) ingress + autoscaling

Parent: #49</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [deploy/helm] Helm chart documentation: SQLite vs Postgres, ingress, autoscaling, common scenarios #212

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR adds comprehensive Helm deployment documentation to make Kubernetes deployments more discoverable and user-friendly. The documentation provides copy-pastable examples for common scenarios (SQLite dev, PostgreSQL production, Redis multi-instance, Ingress with TLS, and HPA autoscaling) while keeping the existing detailed chart-local documentation as the complete reference.

Key Changes:

• Created user-facing Helm deployment guide with 5 quick-start scenarios and production configuration examples
• Updated deployment index to highlight Helm as a primary alternative to AWS ECS with feature comparison
• Added decision guidance to help users choose between Helm and AWS ECS based on their infrastructure

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
docs/deployment/helm.md	New comprehensive Helm deployment guide (379 lines) covering SQLite, PostgreSQL, Redis, Ingress, HPA, dispatcher configuration, verification, and upgrade instructions
docs/deployment/index.md	Updated to add Kubernetes/Helm section with feature highlights and quick-start examples for SQLite and PostgreSQL deployments

[mfittko]

@copilot now fix your comments

[mfittko]

✅ APPROVED - All Issues Resolved

Verification Summary

I've conducted a fresh, comprehensive review of commit 9240f00d and can confirm that all issues from the previous review have been properly addressed.

---

✅ Critical Issues - FIXED

1. Markdown formatting bug (docs/deployment/index.md line 82)

• Status: ✅ FIXED
• What changed: Removed stray leading space before list bullet
• Impact: Markdown now renders correctly without indentation issues

2. Incomplete dispatcher example (docs/deployment/helm.md lines 254-269)

• Status: ✅ FIXED
• What changed:
  • Added kubectl create secret command showing how to create the dispatcher API key secret
  • Added explicit --set dispatcher.apiKey.existingSecret.key="DISPATCHER_API_KEY"
• Impact: Example is now complete and runnable - users won't hit silent failures

---

✅ Strong Recommendations - FIXED

3. OCI vs local path confusion (docs/deployment/helm.md line 47-48)

• Status: ✅ FIXED
• What changed: Added prominent blockquote callout at start of Quick Start Scenarios explaining local path vs OCI registry choice
• Impact: Users now understand when to use deploy/helm/llm-proxy vs oci://ghcr.io/sofatutor/llm-proxy

4. Missing PostgreSQL build requirement (docs/deployment/index.md lines 60-61)

• Status: ✅ FIXED
• What changed: Added blockquote note about custom image build requirements with link to full guide
• Impact: Users won't hit runtime errors when using custom-built images without Postgres support

5. PostgreSQL wording improvement (docs/deployment/helm.md line 93-96)

• Status: ✅ FIXED
• What changed: Changed "Ensure your Docker image" → "If building images yourself" + added note about pre-built images
• Impact: Clearer guidance that doesn't imply universal requirement for all users

---

✅ Minor Issues - FIXED

6. Hard-coded "Last Updated" date (docs/deployment/helm.md line 11)

• Status: ✅ FIXED
• What changed: Removed the hard-coded date
• Impact: Reduces maintenance burden and review friction

---

Fresh Quality Assessment

After a thorough line-by-line review of the updated files (82 lines in index.md, 388 lines in helm.md), I can confirm:

✅ Technical Accuracy

• All env vars, secret keys, and configuration match the codebase
• Event bus backend names (redis-streams, in-memory) are correct
• Dispatcher service names (file, lunary, helicone) match implementation
• ENABLE_METRICS, DB_DRIVER, and other env vars verified against internal/config

✅ Security Best Practices

• All DATABASE_URL examples use uppercase placeholders (USER:PASSWORD)
• sslmode=verify-full used consistently (not sslmode=require)
• Warning comments about never committing real secrets are present
• Redis password generation uses openssl rand -base64 32

✅ Documentation Quality

• Clear progression from simple (SQLite dev) to complex (multi-replica prod with HPA)
• Copy-pastable examples that actually work
• Helpful callouts and prerequisites for each scenario
• Good cross-references to chart-local docs and related guides
• Comparison table provides clear guidance for AWS ECS vs Helm choice

✅ Consistency

• Formatting is clean and consistent throughout
• Markdown renders correctly (verified by checking structure)
• Links are correct (fixed in previous review round)
• No unresolved TODOs or placeholders

---

Production Readiness

This documentation is production-ready and meets all quality standards:

1. ✅ Complete - All deployment scenarios covered (SQLite, Postgres, Redis, Ingress, HPA, Dispatcher)
2. ✅ Correct - Technical details verified against codebase
3. ✅ Secure - Security best practices followed throughout
4. ✅ Usable - Examples are runnable and well-explained
5. ✅ Maintainable - No hard-coded dates, clear structure

---

Final Verdict

APPROVED ✅

This PR successfully delivers comprehensive Helm deployment documentation that will help users deploy LLM Proxy to Kubernetes with confidence. All critical issues have been resolved, security concerns addressed, and the documentation provides clear, accurate guidance for both development and production scenarios.

Excellent work addressing all the review feedback thoroughly and thoughtfully!

Ready to merge.

[mfittko]

✅ Perfect fix - The OCI vs local path callout is clear and well-placed. Users now understand the choice without being confused by the examples. This addresses the original concern about repo checkout requirements beautifully.

[mfittko]

✅ Excellent wording improvement - "If building images yourself" is much clearer than the previous "Ensure your Docker image". The added note about pre-built images from ghcr.io is perfect for preventing user confusion. This is exactly what was needed.