docs: Edge Proxy operational guide (troubleshooting, advanced config, Rust proxy)

[Holmus]

Problem

The Edge Proxy documentation covers basic Docker deployment and configuration options but lacks operational guidance for running it in production. Support tickets for Edge Proxy issues frequently escalate to engineering because the troubleshooting steps aren't documented anywhere, and the deployment guidance doesn't extend beyond basic Docker CLI/Compose examples.

Real support patterns (anonymized)

We reviewed 9 Edge Proxy support tickets from the last 5 months. These are the recurring issues, paraphrased from real tickets:

1. Identity overrides not working through Edge Proxy

"Edge Proxy ignores identity overrides and returns environment-level flag values instead."

"Evaluation result is incorrect when our Node.js client is connected to Edge Proxy server."

This is the most confusing issue for users. They set up identity overrides in the dashboard, everything works when hitting the API directly, but the Edge Proxy returns different values. No documentation explains whether this is expected behavior, a configuration issue, or a limitation.

2. 403 errors and restart loops

"Our production Edge Proxy got stuck in a loop trying to restart the ECS Fargate service. The underlying error was an HTTP 403."

"We've been running a Flagsmith Edge Proxy for a while but our backends were not configured to use it. When I tried to point them at it, I got unauthorized key errors."

403 errors are the most common Edge Proxy support issue. Causes vary (wrong key type, expired key, API URL misconfiguration) but there's no troubleshooting guide to walk through diagnosis.

3. Scaling and performance questions

"We need advice ASAP - will increasing the number of Edge Proxies move the bottleneck to the Core API?"

"Does the Edge Proxy support user traits and identity-based evaluation?"

Users making scaling decisions have no guidance on Edge Proxy capacity planning or architectural implications.

4. Configuration and key management

"I've hit a problem with our CodeQL scanner in GitHub. In my Edge Proxy repo, I have a config file with environment key pairs. How should we manage these?"

"Edge Proxy environment key pair has a blank server key - is this expected?"

Operational questions about securely managing Edge Proxy configuration in CI/CD pipelines and infrastructure-as-code.

5. Compatibility and deployment beyond Docker

Users deploying on ECS/Fargate, behind load balancers, or in Kubernetes hit issues not covered by the Docker CLI/Compose examples. Health check configuration, proxy headers, and networking requirements are common friction points.

What's missing

Identity overrides in Edge Proxy

• Do identity overrides work through the Edge Proxy? If so, how?
• Any limitations compared to hitting the API directly?
• Configuration needed to enable identity override support
• If this is a known limitation, say so explicitly

Troubleshooting common errors

• 403 Forbidden: Most common issue. Step-by-step diagnosis: check key type (must be server-side), verify environment key matches, check API URL configuration, verify network connectivity to Flagsmith API.
• Restart loops: Common in container orchestration (ECS, K8s). Causes: health check failures during environment document initial fetch, incorrect readiness probe configuration.
• Stale flags after deployment: Environment document polling not picking up changes. How to verify the proxy is polling correctly.
• Incorrect evaluation results: Identity override behavior, cache staleness, environment document version.

Deployment beyond Docker CLI

• ECS/Fargate: Task definition considerations, health check configuration, networking (proxy needs outbound to Flagsmith API).
• Kubernetes: Helm chart reference if available, resource recommendations, liveness/readiness probe paths.
• Behind a load balancer: Proxy header forwarding, session handling.

Caching and architecture

• How the endpoint LRU cache works in practice
• Recommended sizing for different scales
• How Edge Proxy fits architecturally (clients -> Edge Proxy -> Flagsmith API) and what calls go where
• When to use one proxy vs. multiple, and implications for the Core API

Rust Edge Proxy

• The new Rust-based Edge Proxy should be referenced as an alternative
• Link to the Rust Edge Proxy repository and its documentation
• Key differences: performance characteristics, feature parity, configuration format
• Guidance on when to use which implementation

Suggestion

Extend the existing Edge Proxy page with an "Operations" or "Running in Production" section. The troubleshooting section is the highest priority - it would immediately deflect the most common support escalations.

Structure suggestion:

1. Current content (setup, config) - keep as-is
2. New: "Identity Overrides" - clear statement of behavior and limitations
3. New: "Troubleshooting" - symptom-first diagnosis guides
4. New: "Production Deployment" - beyond Docker CLI examples
5. New: "Rust Edge Proxy" - alternative implementation reference

Why this matters

Edge Proxy users are self-hosted customers running Flagsmith in production infrastructure. When they hit issues, they're often blocked on a deployment or experiencing production impact. These are the tickets most likely to pull an engineer away from product work, since they require infrastructure knowledge to debug. A troubleshooting guide here directly reduces engineering support load and improves the self-hosted customer experience.