Axum: document Docker, Kubernetes, and managed-cloud deployments #400

Part of #391.

Description

Provide tested deployment guidance for applications built with EdgeZero's native Axum adapter. EdgeZero owns the generic runtime and packaging contract; application repositories such as Trusted Server own their images, credentials, configuration, and deployment releases.

Current state

The Axum guide has a short outdated Docker example, but no tested Kubernetes or managed-container deployment recipe. #398 owns the Docker packaging implementation and #399 owns architecture CI and the application publishing recipe. Neither is the right place to maintain the full operator deployment guide.

Trusted Server's #897 self-hosting proposal is a downstream application/installer story, not an EdgeZero deployment framework. Its config, stores, signing, and consent requirements must not become assumptions hidden inside generic manifests.

Proposed solution

1. Start with Docker run/Compose guidance using Axum: scaffold hardened production application Dockerfiles #398's tested recipe. Explain ports/bind address, TLS termination, configuration and secrets, writable mounts, UID permissions, logging, health/readiness, and SIGTERM handling.
2. Provide minimal Kubernetes manifests for a test application: workload, Service, explicit probe wiring, security context, resource configuration, termination grace, and configuration/secret references. Explain ingress or Gateway/TLS integration without embedding vendor-specific credentials or controllers.
3. Separate stateless/multi-replica examples from embedded redb. An embedded store requires single-writer ownership, durable storage, and a rollout strategy that does not overlap writers. A shared filesystem is not a multi-writer database.
4. Add one managed-container recipe after recording the target and prerequisites. ECS/Fargate is a candidate, not a committed selection or support claim. Evaluate Cloud Run/Azure Container Apps as follow-ups against storage, supported architecture, port injection, request/stream lifetimes, shutdown, and scaling needs.
5. Document image-digest deployment, config/key update ownership, upgrades, rollback, and troubleshooting. Reference Axum: validate multi-platform containers and provide an application publishing workflow #399 for publishing/security metadata, not a second workflow implementation.
6. Use an application fixture for verification. Provide a mapping to Trusted Server's app-owned image/deployment docs, without copying its secrets, production configuration, or application feature policy.

Sequence and dependencies

• Documentation structure and example manifests can be drafted while feat: implement portable outbound HTTP and request lifecycle contracts #275 is open.
• Runnable Docker instructions depend on Axum: scaffold hardened production application Dockerfiles #398; architecture claims depend on Axum: validate multi-platform containers and provide an application publishing workflow #399.
• Runtime semantics come from accepted PR #275, Axum: define a production server lifecycle with bounded graceful shutdown #392 lifecycle/readiness, Axum: make production configuration and local storage explicit #396 configuration/storage, and the relevant Axum: enforce configurable buffered request-body limits #393/Axum: preserve incremental streaming with bounded backpressure #394/Axum: reuse outbound clients and preserve proxy HTTP semantics #395/Axum: add safe production diagnostics and trusted-proxy handling #397 acceptance checks.
• Do not advertise a recipe as production-verified until its actual deployment and restart/upgrade/rollback checks have been run. Keep unverified targets explicitly marked.

Done when

• Docker documentation uses the tested packaging recipe and covers non-root/read-only execution with explicit writable mounts.
• Kubernetes examples validate and run in a disposable cluster, with tested startup/readiness, failed initialization, SIGTERM/draining, restart, and the documented rollout behavior.
• The guide distinguishes app-owned readiness/dependencies from process liveness and documents TLS/proxy trust boundaries.
• Storage/replica assumptions are explicit; examples do not imply redb supports concurrent writers or that all apps are stateless.
• The first managed-container target is selected with rationale, then exercised in an authorized test deployment; remaining cloud candidates are clearly unverified.
• Architecture, HTTP protocol, stream/deadline, and BestEffort/Unsupported constraints match the accepted runtime evidence.
• Upgrade and rollback examples use retained image digests and explain configuration/secret compatibility.
• Downstream application responsibilities and links to Trusted Server's self-hosting work are clear.

Non-goals

No public EdgeZero application or custom base image, Kubernetes operator, general cloud provisioning CLI, blanket all-cloud support claim, or requirement to add Helm before plain manifests demonstrate a need. Trusted Server's actual deployment manifests and ts up stay in its repository.

Affected areas

Documentation; CI / Tooling; Adapter -- Axum.

Implementation and relationship tracking

No published implementation PR currently represents this issue. GitHub records #398 and #399 as prerequisites for runnable packaging and architecture-backed guidance. Documentation preparation may proceed while they are open; production claims still require the runtime and deployment evidence described above.