Deployment Overview¶

Deployment status: Reference deployment guide. The actual deployment topology, service commands, health checks, and infrastructure configuration must be verified against the repository and deployment environment before release approval.

This guide establishes a consistent approach to deploying, validating, monitoring, and rolling back WhiteLotusAI. It defines the operational requirements for reproducible releases while distinguishing documented deployment practices from implementation details that still require verification.

1. Deployment objectives¶

A reliable deployment should satisfy the following objectives:

Development, staging, and production must use appropriately isolated credentials, configuration, and data. Production deployment should proceed only when the required validation and recovery procedures are understood.

2. Deployment inventory¶

Before deploying a release, establish the actual runtime topology and record the evidence supporting it.

3. Release lifecycle¶

The following workflow defines the recommended release process. Individual steps may be automated by CI/CD, but automation must be verified rather than assumed.

flowchart TD
    A["Review and merge change"] --> B["Run tests and security checks"]
    B --> C{"Quality gates pass?"}
    C -- "No" --> X["Resolve issues and rerun checks"]
    X --> B
    C -- "Yes" --> D["Build and identify immutable artifact"]
    D --> E["Validate configuration and secrets"]
    E --> F["Back up persistent data when required"]
    F --> G["Deploy to controlled environment"]
    G --> H["Run smoke and integration checks"]
    H --> I{"Release healthy?"}
    I -- "No" --> J["Investigate and roll back when appropriate"]
    I -- "Yes" --> K["Promote or approve release"]
    K --> L["Record outcome and follow-up actions"]

    classDef process fill:#e8f0ff,stroke:#5575b8,color:#172554,stroke-width:1px
    classDef decision fill:#fff0cc,stroke:#b7791f,color:#78350f,stroke-width:1px
    classDef success fill:#d9fbe8,stroke:#23865b,color:#14532d,stroke-width:1px
    classDef failure fill:#ffe4e6,stroke:#be5363,color:#881337,stroke-width:1px

    class A,B,D,E,F,G,H,K,L process
    class C,I decision
    class X,J failure

Release gates¶

4. Environment and configuration management¶

Maintain separate configuration for each deployment environment. Store non-secret defaults in version-controlled templates and inject credentials through an approved secret manager or protected runtime environment.

Configuration principles¶

• Keep development, staging, and production credentials separate.
• Grant each service only the permissions it requires.
• Validate required variables before starting the application.
• Keep database URLs, signing keys, OAuth secrets, and internal service credentials out of source control.
• Avoid exposing secret values in logs, command output, error messages, or build artifacts.
• Rotate credentials according to the organization's security policy.
• Document variable names, purposes, required status, and ownership without publishing their values.

Example: safe configuration validation¶

The following example illustrates how a deployment pipeline can check that required variables are present without printing their values. Adapt the variable names to the application's actual configuration contract.

#!/usr/bin/env bash
set -euo pipefail

required_vars=(
  DATABASE_URL
  JWT_SECRET_KEY
  INTERNAL_SERVICE_SECRET
)

missing=0

for name in "${required_vars[@]}"; do
  if [[ -z "${!name:-}" ]]; then
    printf 'ERROR: Required variable is missing: %s\n' "$name" >&2
    missing=1
  fi
done

if [[ "$missing" -ne 0 ]]; then
  printf 'Configuration validation failed.\n' >&2
  exit 1
fi

printf 'Required configuration variables are present.\n'

Environment responsibilities¶

5. Startup, health, and readiness¶

A running container is not necessarily a ready application. Deployment verification should distinguish process startup from application readiness and successful dependency communication.

Where supported, use health checks with meaningful timeouts and retry policies. Avoid declaring readiness solely because a TCP port is open.

For asynchronous workers, readiness should reflect the worker's ability to initialize required dependencies and process its intended workload. Do not introduce a health endpoint solely for documentation purposes; confirm the implementation first.

6. Smoke testing after deployment¶

Run a small, repeatable set of checks immediately after deployment. The exact commands depend on the actual service interfaces and environment.

• Confirm that expected application processes and containers are running.
• Verify implemented health and readiness checks.
• Confirm that required dependencies are reachable.
• Inspect startup logs for configuration errors, repeated retries, or unexpected crashes.
• Validate authentication and authorization using an approved test account.
• Run a representative read-only integration workflow.
• Confirm that failed requests are handled safely and do not expose secrets.
• Review resource consumption, request latency, and error rates.
• Confirm that the previous release and recovery instructions remain identifiable.

7. Database changes and persistent data¶

Database migrations and persistent storage changes require explicit consideration before release.

1. Identify schema and data changes introduced by the release.
2. Determine whether the migration is backward-compatible with the currently deployed application.
3. Confirm that required backups exist and that restoration procedures are understood.
4. Apply migrations using the repository's supported migration mechanism.
5. Verify the resulting schema and critical application workflows.
6. Record any migration that cannot safely be reversed.

Prefer backward-compatible, staged migrations when application versions may overlap during deployment. A database rollback is not always equivalent to rolling back an application image.

8. Rollback and recovery¶

Rollback should restore a known-good application state without compromising data integrity or security.

Rollback procedure¶

1. Detect: Identify the release-blocking failure using health checks, logs, monitoring, or failed smoke tests.
2. Assess: Determine whether the failure is application-related, configuration-related, dependency-related, or caused by a data migration.
3. Contain: Stop further promotion and prevent additional risky changes.
4. Restore: Redeploy the known-good artifact and compatible configuration when safe.
5. Validate: Recheck readiness, critical workflows, and representative read-only integration behavior.
6. Record: Document the cause, recovery actions, impact, and corrective work.

Keep the following information available for each release:

9. Resource planning and operational limits¶

Set resource allocations based on measured workload, model requirements, dependency behavior, and the target infrastructure.

Consider the following when defining deployment capacity:

• CPU and memory: Include application workers, model inference, embedding generation, and background processing.
• Storage: Account for logs, uploaded documents, vector data, model artifacts, and database growth.
• Concurrency: Establish limits for simultaneous requests, provider calls, and background jobs.
• Network: Account for internal service communication and external provider dependencies.
• Timeouts and retries: Avoid retry patterns that amplify outages or exhaust available resources.
• Scaling: Confirm that persistent state, message processing, and session handling support the intended scaling strategy.

Do not select production limits solely from development-machine measurements. Validate resource consumption under representative workloads in an environment comparable to the intended deployment target.

10. Release records and evidence¶

Maintain a release record for traceability and incident investigation.

The release record should reference relevant evidence, such as CI/CD job results, deployment logs, security checks, migration records, and recovery validation. Do not include raw secrets, access tokens, or sensitive production data.

11. Repository verification references¶

Before treating this guide as an implementation-specific runbook, map each deployment claim to its actual source.

Use the actual repository paths in the final documentation once verified. A file's existence does not by itself establish that its behavior is correct or exercised in production.

12. Deployment readiness checklist¶

Use this checklist as a release review aid.

• The release artifact and source revision are identifiable.
• Required tests and security checks have passed.
• Environment configuration is validated and secrets are protected.
• Network exposure and access permissions have been reviewed.
• Persistent data and migration risks have been assessed.
• Resource limits and external dependencies are understood.
• Implemented health and readiness checks have been verified.
• Representative smoke tests have passed.
• A known-good artifact and feasible rollback procedure are available.
• The release record contains validation results and outstanding risks.

Related documentation¶

• Deployment configuration — environment-specific settings and deployment configuration, if maintained.
• AWS deployment — AWS-specific deployment guidance, if maintained.
• Docker deployment — container-based deployment instructions, if maintained.
• Architecture overview — system boundaries and component responsibilities.
• Security overview — security controls and deployment considerations.