docs(v2): add production readiness guide

[erka]

No description provided.

[claude]

Review: Production Readiness Guide

Overall this is a well-structured, useful guide. The content is clear, uses second-person voice throughout, and the dual-tab pattern (env var + YAML) is consistent with the rest of the docs. A few things worth addressing before merging:

---

Bug: Navigation placement in docs.json

The page is added as a flat entry directly under "Operations Guides", but the file lives at v2/guides/operations/deployment/production. It should be inside the "Deployment" subgroup alongside the other deployment pages:

// Current (incorrect) — page floats above all subgroups
{
  "group": "Operations Guides",
  "pages": [
    "v2/guides/operations/deployment/production",  // ← out of place
    {
      "group": "Deployment",
      "pages": [...]
    },
    ...
  ]
}

// Correct — page lives inside its matching subgroup
{
  "group": "Deployment",
  "pages": [
    "v2/guides/operations/deployment/production",
    "v2/guides/operations/deployment/deploy-to-kubernetes",
    "v2/guides/operations/deployment/kubernetes-troubleshooting"
  ]
}

---

Storage section: git remote authentication is missing

The example config uses a plain HTTPS URL with no guidance on credentials:

storage:
  default:
    backend:
      type: local
      path: /var/lib/flipt
    remote: https://github.com/your-org/flags.git

In a real production environment the git remote will need authentication (token in URL, SSH key, etc.). Even a brief note pointing to the Git Sync guide for credential setup would avoid confusion for readers who copy this config verbatim and get authentication errors.

---

CORS: multi-origin env var syntax unclear

The YAML variant shows a list, but the env var example only shows a single value. If FLIPT_CORS_ALLOWED_ORIGINS accepts a comma-separated list for multiple origins, it would help to document that pattern:

# If multiple origins are supported:
FLIPT_CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com

If only a single value is supported via env var, the YAML should be the recommended path for multi-origin setups.

---

Minor

• Intro sentence: "quick starts" reads a bit awkward — "quick start" (singular) is the more common phrasing.
• RBAC mention: "configure RBAC policies to restrict what authenticated users can do" — if RBAC is a Pro-only feature, it's worth a small callout so open-source users aren't confused when they can't find the setting.
• TLS/HTTPS: Production readiness guides typically call out TLS termination. Even a sentence noting that TLS should be handled at the load balancer / ingress level (with a pointer to the Kubernetes guide) would complete the security picture.

---

The content itself is accurate and follows the style guide well. Fixing the docs.json placement is the main blocker — everything else is suggestions for improvement.

[claude]

Review: Production Readiness Guide

Great addition — a production readiness checklist is genuinely useful and covers the right surface area. A few things to address before merging:

---

Bug / Accuracy issues

1. Missing link to Authorization docs (Authentication and Authorization section)

The section mentions "configure RBAC policies" but doesn't link to the authorization configuration page. The existing /v2/configuration/authorization.mdx covers this in detail and should be referenced. Consider adding a sentence like:

For fine-grained access control, configure RBAC policies using OPA-based authorization to restrict what authenticated users can do.

The "Next Steps" section also omits the Authorization docs.

2. Storage YAML example — unquoted strings

The PR uses unquoted YAML strings (path: /var/lib/flipt, branch: main) while the existing storage.mdx examples consistently use quoted strings. For consistency and to avoid YAML edge-case confusion:

storage:
  default:
    backend:
      type: local
      path: "/var/lib/flipt"
    remote: "https://github.com/your-org/flags.git"
    branch: "main"

3. Storage example — no mention of credentials

The remote URL uses plain HTTPS (https://github.com/your-org/flags.git). For private repositories (the typical production case), credentials are required. The storage docs have a full Credentials section. Worth adding a note like:

For private repositories, you'll also need to configure credentials.

---

Writing / style

4. Frontmatter description is awkward

"Reviewing configuration options for operating Flipt v2 in production"

"Reviewing" implies the user is reviewing, not the doc. Per Microsoft Writing Style Guide, prefer active, direct phrasing:

"Key configuration options for running Flipt v2 reliably in production"

5. CORS section — "wildcard * default"

The note says "rather than using the wildcard * default". To be precise, * is the default for allowed_origins only when CORS is enabled — when cors.enabled: false (the actual default), there is no CORS restriction at all. Slight rewording to avoid confusion:

Restrict allowed_origins to your known frontend URLs rather than relying on the wildcard *.

---

What looks good

• Tab components with env var + YAML alternatives — consistent with existing patterns.
• Security framing on profiling (/debug/pprof) and Prometheus metrics — correct and practical.
• ClickHouse mention in Backup Strategy is accurate and relevant.
• meta.check_for_updates / FLIPT_META_CHECK_FOR_UPDATES — confirmed against overview.mdx.
• Navigation placement in docs.json (top of Operations Guides group) makes sense for discoverability.

---

Overall this is solid content. The main asks are: link to authorization docs, add a credentials callout in the storage example, and fix the description frontmatter.

[claude]

PR Review: Production Readiness Guide for v2

This is a solid, well-structured page that fills an important gap in the v2 docs. The consistent use of <Tabs> for env var/YAML alternatives, proper frontmatter, language-tagged code blocks, and relative internal links all look great. A few things worth addressing before merging:

---

Issues

1. Missing fetch_policy: strict recommendation (important)

The storage docs include an explicit <Warning> recommending fetch_policy: strict in production to ensure connectivity issues are detected promptly. The storage config example in this guide omits it entirely, which contradicts what the storage docs advise:

storage:
  default:
    backend:
      type: local
      path: /var/lib/flipt
    remote: "https://github.com/your-org/flags.git"
    branch: main
    fetch_policy: strict   # ← missing from the PR

Consider adding a note and including it in the example YAML.

2. No TLS/HTTPS section

Enabling TLS on the HTTP/gRPC server is arguably the most fundamental production security step. It's missing from the guide entirely. At minimum, a short section pointing to the relevant configuration (or a note that TLS should be terminated at the ingress/load balancer) would round out the security coverage.

3. Missing analytics docs link in Backup Strategy

The Backup Strategy section mentions ClickHouse but doesn't link to the analytics configuration docs. Consider adding a link to /v2/configuration/analytics here:

If using ClickHouse, ensure that data is backed up according to your organizational policies.

→ something like: "If using ClickHouse for analytics, ensure..."

4. Multi-origin CORS env var

The CORS env var example only shows a single origin:

FLIPT_CORS_ALLOWED_ORIGINS=https://app.example.com

Does the env var support comma-separated values for multiple origins? If so, this should be documented. If not, readers with multiple subdomains won't know what to do.

---

Minor

5. Storage example values aren't quoted

The remote URL and branch in the storage YAML aren't quoted, while the storage docs consistently quote strings. Minor inconsistency but worth being consistent:

remote: "https://github.com/your-org/flags.git"
branch: "main"

6. "Restrict access to internal networks" in Profiling section has no actionable guidance

If you need profiling in production, restrict access to internal networks only.

This is good advice but leaves readers without a hint of how. A brief pointer (e.g., "via your reverse proxy or Kubernetes NetworkPolicy") or a link to the deployment guide would help.

7. Update Checks section — consider noting startup delay in air-gapped envs

In air-gapped environments where the update check is left enabled, startup could be delayed by a network timeout. If that's the case for Flipt, it's worth calling out explicitly so operators know to disable it proactively rather than debugging slow starts.

---

Nits

• The intro could mention that this guide covers the most impactful changes (rather than being exhaustive), setting expectations correctly.
• The Backup Strategy section is a bit thin on the "how". Even a one-liner like "Use git remote add mirror <url> && git push mirror --mirror or your Git provider's built-in mirroring" would make it more actionable.

---

Overall this is a valuable addition. The structure is clean and the coverage of logging, profiling, auth, metrics, and CORS is well done. The main ask before merging is the fetch_policy: strict gap and the missing TLS guidance.

[markphelps]

one comment for clarity, otherwise lgtm

[markphelps]

i feel like this is a bit confusing since the Flipt UI is a react app. Perhaps we should say something like "If you are integrating Flipt v2 with a client side frontend.." or similar?

[claude]

Code Review — Production Readiness Guide

Overall this is a valuable addition. The page is well-structured, consistently formatted, and covers the most important operational concerns. A few things worth addressing before merging:

---

Issues

1. Storage section — misleading path semantics

The example uses:
```yaml
storage:
default:
backend:
type: local
path: /var/lib/flipt
remote: https://github.com/your-org/flags.git
branch: main
```

Looking at the existing git-sync guide, path must point to a local git clone, not an arbitrary directory. A user who creates /var/lib/flipt without initializing it as a git repository will hit a confusing failure. The existing storage docs call this "path to local clone." A brief note here (or a link to the Git Repository Initialization guide) would help.

2. CORS — multiple origins via env var is ambiguous

The YAML shows allowed_origins as an array, but the env var example only shows a single value:
```bash
FLIPT_CORS_ALLOWED_ORIGINS=https://app.example.com
```
It's unclear how to set multiple origins via environment variable (comma-separated? repeated variable?). Either show the multi-value syntax or add a note that multiple origins require the YAML config.

3. Update Checks — "security-sensitive" is imprecise

This can be disabled in air-gapped or security-sensitive environments

The actual reason is network restriction (air-gapped) or preventing outbound connections to Flipt's update server. Calling it a "security" concern implies a risk that doesn't really exist for most users. Suggest: "This can be disabled in air-gapped environments or to prevent outbound network traffic on startup."

---

Suggestions

4. Backup Strategy — link to Analytics docs

The section mentions ClickHouse but doesn't link to /v2/configuration/analytics where users can find setup details and backup guidance. A link would complete the picture.

5. Prometheus metrics — missing actionable guidance

The section recommends restricting /metrics access via "network policies, reverse proxy rules, or your ingress configuration" but gives no examples or links. Consider linking to the Kubernetes deployment guide or adding a minimal nginx/ingress snippet since this is the most common production deployment path.

6. Consider a TLS/HTTPS section

Standard production readiness guides cover TLS termination. If Flipt always delegates TLS to a reverse proxy/ingress (which seems to be the intent from the Kubernetes guide), it's worth a one-liner callout explaining that, so users don't wonder why it's absent.

---

Minor

• The diagnostics.profiling.enabled env var name reads a bit oddly (FLIPT_DIAGNOSTICS_PROFILING_ENABLED) — worth a quick double-check against the actual config schema to confirm it matches.
• The <Tab> indentation style (4-space indent inside tab blocks) matches the existing analytics/auth docs — consistent. ✅
• All code blocks have language tags. ✅
• All internal links use relative paths. ✅
• Second-person voice throughout. ✅