AWS Deployment¶

Document status: Deployment reference
Scope: AWS infrastructure, application delivery, security, recovery, and operational readiness
Verification: Confirm all environment-specific values against the active AWS account, deployment configuration, and approved operational procedures before use.

1. Purpose¶

This document defines the infrastructure inventory, deployment workflow, security requirements, and operational controls for deploying WhiteLotusAI on Amazon Web Services (AWS).

The actual instance types, network topology, managed services, public endpoints, and deployment mechanisms must be verified before this document is treated as an executable runbook. Examples and recommendations in this guide are not evidence that a particular AWS resource has already been provisioned.

2. Deployment architecture¶

The following diagram illustrates a recommended deployment pattern. It is a logical reference, not a representation of verified production infrastructure.

flowchart TD
    U["Users and administrators"] --> TLS["HTTPS entry point<br/>Load balancer or approved ingress"]
    TLS --> APP["WhiteLotusAI application<br/>Frontend and API gateway"]

    APP --> SVC["Application services<br/>Chat, integrations and workers"]
    SVC --> DB[("Database<br/>Persistent application data")]
    SVC --> CACHE[("Cache and messaging<br/>If configured")]
    SVC --> AI["AI inference provider<br/>Local or external, as configured"]

    APP --> OBS["Logs, metrics and alerts"]
    SVC --> OBS

    CI["CI/CD pipeline"] --> REG["Amazon ECR<br/>Versioned container images"]
    REG --> DEP["Approved deployment process"]
    DEP --> APP

    IAM["IAM roles and policies"] -. "Access control" .-> APP
    SEC["Secrets management"] -. "Runtime credentials" .-> SVC

    classDef entry fill:#DCEAFE,stroke:#2563EB,color:#172554,stroke-width:1.5px
    classDef app fill:#EDE9FE,stroke:#7C3AED,color:#3B0764,stroke-width:1.5px
    classDef data fill:#D1FAE5,stroke:#059669,color:#064E3B,stroke-width:1.5px
    classDef ops fill:#F3F4F6,stroke:#64748B,color:#1F2937,stroke-width:1.5px
    class U,TLS entry
    class APP,SVC,AI app
    class DB,CACHE,REG data
    class OBS,CI,DEP,IAM,SEC ops
    linkStyle default stroke:#64748B,stroke-width:1.3px

Architecture principles¶

• Minimize public exposure: Only approved entry points should accept inbound internet traffic.
• Isolate internal services: Databases, caches, message brokers, and internal APIs should not be publicly accessible unless explicitly justified.
• Separate deployment from runtime: Build and scan release artifacts before deploying them.
• Centralize operational visibility: Collect application logs, infrastructure metrics, deployment events, and security-relevant events.
• Make recovery testable: Maintain documented rollback and data-restoration procedures.

3. Infrastructure inventory¶

Maintain an up-to-date inventory for each environment. Record resource identifiers in an approved internal system rather than publishing sensitive infrastructure details in public documentation.

Record environment-specific values in an internal deployment inventory:

Do not assume that development, staging, and production share the same credentials, network permissions, or data-retention requirements.

4. Identity and access management¶

Use AWS Identity and Access Management (IAM) to assign the minimum permissions required for each deployment and runtime responsibility.

Required controls¶

• Prefer IAM roles and temporary credentials over long-lived access keys.
• Separate CI/CD permissions from application runtime permissions.
• Restrict ECR access to the repositories and operations required by each role.
• Limit administrative access to approved personnel and controlled access methods.
• Review trust relationships, unused permissions, and privileged roles periodically.
• Enable appropriate audit logging for identity and infrastructure changes.
• Never commit AWS access keys, private keys, tokens, or production secrets to source control.

5. Release and deployment workflow¶

A production deployment should be repeatable, auditable, and reversible wherever the data model permits.

flowchart TD
    A["Prepare release<br/>Review changes and version"] --> B["Run tests and security checks"]
    B --> C{"Checks passed?"}
    C -- "No" --> X["Stop release<br/>Fix and revalidate"]
    C -- "Yes" --> D["Build and scan images"]
    D --> E["Publish immutable release artifact"]
    E --> F["Apply approved configuration"]
    F --> G["Run compatible migrations"]
    G --> H["Deploy release"]
    H --> I["Run health and smoke tests"]
    I --> J{"Acceptance criteria met?"}
    J -- "Yes" --> K["Monitor rollout<br/>Record release evidence"]
    J -- "No" --> L["Initiate rollback or recovery"]
    L --> M["Verify service and data integrity"]

    classDef action fill:#DCEAFE,stroke:#2563EB,color:#172554,stroke-width:1.5px
    classDef decision fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:1.5px
    classDef success fill:#D1FAE5,stroke:#059669,color:#064E3B,stroke-width:1.5px
    classDef failure fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:1.5px
    class A,B,D,E,F,G,H,I action
    class C,J decision
    class K success
    class X,L,M failure
    linkStyle default stroke:#64748B,stroke-width:1.3px

Pre-deployment checklist¶

• Confirm the release version and reviewed source revision.
• Run unit, integration, and relevant end-to-end tests.
• Scan dependencies and container images.
• Verify image provenance and registry permissions.
• Validate environment configuration and secret references.
• Confirm database migration compatibility and recovery options.
• Check resource capacity, health checks, and service dependencies.
• Confirm monitoring, alerting, and rollback ownership.

Deployment checklist¶

• Deploy the approved, versioned artifact.
• Apply only reviewed infrastructure or configuration changes.
• Execute database migrations using the approved procedure.
• Verify service startup, readiness, and dependency connectivity.
• Run authentication, authorization, API, and critical workflow smoke tests.
• Check error rates, latency, resource utilization, and application logs.
• Record the outcome and any follow-up actions.

6. Container image delivery¶

If WhiteLotusAI uses Amazon Elastic Container Registry (Amazon ECR), maintain a clear separation between image creation, publication, and deployment.

The following is a generic example of authenticating to ECR and publishing a tagged image. Replace the placeholders with verified values and run it only from an authorized environment.

# Replace placeholders before execution.
export AWS_REGION="<aws-region>"
export AWS_ACCOUNT_ID="<aws-account-id>"
export ECR_REPOSITORY="<repository-name>"
export IMAGE_TAG="<release-tag>"

export ECR_REGISTRY="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"

aws sts get-caller-identity

aws ecr get-login-password --region "$AWS_REGION" \
  | docker login \
      --username AWS \
      --password-stdin "$ECR_REGISTRY"

docker build -t "${ECR_REPOSITORY}:${IMAGE_TAG}" .

docker tag "${ECR_REPOSITORY}:${IMAGE_TAG}" \
  "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}"

docker push "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}"

This example publishes an image; it does not deploy the application. Validate the AWS identity, repository, region, image scan results, and release tag before running the commands.

7. Network security¶

Apply a deny-by-default approach wherever supported and allow only explicitly required traffic.

Network review requirements¶

• Verify security group references and outbound destinations.
• Avoid exposing database, Redis, RabbitMQ management, and internal service ports directly to the internet.
• Enforce HTTPS for public application traffic.
• Restrict administrative access using approved identity and network controls.
• Review DNS records, certificate expiry, and TLS termination.
• Verify service-to-service authentication independently of network location.
• Document any necessary public exception, its owner, and its expiration or review date.

The exact ports and routing rules must be derived from the deployed service configuration rather than assumed from application defaults.

8. Configuration and secrets¶

Keep non-sensitive configuration separate from secret material.

Never expose secrets in API responses, application logs, CI/CD output, browser-delivered configuration, or error messages. Define ownership and rotation procedures for every production credential.

9. Resource capacity and performance¶

Capacity planning must be based on measurements from representative workloads, not solely on instance specifications.

Monitor:

• CPU utilization and throttling.
• Memory consumption and out-of-memory events.
• Disk usage and container image growth.
• Request concurrency, throughput, latency, and error rates.
• Database connection counts and query performance.
• Redis memory, cache hit rate, and connection usage.
• RabbitMQ queue depth and consumer health, if deployed.
• AI inference latency, model memory requirements, and provider limits.
• Restart frequency and readiness or liveness failures.

For a resource-constrained deployment, load-test the complete application stack—including the model service, if colocated—before selecting production capacity.

Define measurable thresholds for scaling, alerting, and release acceptance.

10. Observability and incident response¶

A production deployment should provide sufficient evidence to detect failures, diagnose their cause, and verify recovery.

Use structured logs and correlation identifiers where practical. Redact access tokens, credentials, and sensitive document content. Define alert routing, escalation ownership, and retention requirements according to the environment's operational and compliance needs.

11. Backup, recovery, and rollback¶

Document the recovery requirements before production approval.

RPO and RTO must be approved business requirements, not guessed values.

Recovery procedures should cover both application failure and persistent-data failure. Restoring a database backup may require coordinated recovery of uploaded documents, configuration, and related records.

12. Production readiness gate¶

Use this checklist before authorizing production traffic.

• Infrastructure inventory and ownership are documented.
• IAM roles and permissions have been reviewed.
• Public ingress and security group rules have been verified.
• TLS, DNS, and certificate renewal are operational.
• Secrets are securely stored and access is restricted.
• Release artifacts are versioned and security-checked.
• Database migrations and recovery procedures are approved.
• Health checks and critical user workflows pass.
• Logs, metrics, dashboards, and actionable alerts are available.
• Capacity and failure behavior have been tested.
• Backup restoration and rollback procedures have been exercised.
• Incident ownership and escalation paths are defined.

Production approval should be recorded by the designated owner with references to the evidence supporting each critical control.

13. Deployment record¶

Maintain a record for each production release.

14. Related documentation¶

• Deployment overview
• Docker deployment
• Architecture overview
• Security overview
• Troubleshooting

Verify these relative paths against the current documentation tree before publishing.

Maintenance: Review this guide whenever the AWS topology, deployment pipeline, identity model, recovery requirements, or production operating procedures change.