Docker Deployment¶

Deploy and validate WhiteLotusAI using Docker Compose. This guide covers the inspected development and production-oriented configurations, service dependencies, network routing, persistent storage, and operational safeguards.

1. Deployment overview¶

WhiteLotusAI uses Docker Compose to orchestrate application services and supporting infrastructure. The repository contains two primary Compose configurations:

• docker-compose.yaml — local development and service orchestration.
• docker-compose.prod.yaml — production-oriented orchestration, including the frontend, Nginx, and Certbot.

Architecture¶

flowchart TB
    Client["Browser / Client"]

    subgraph Edge["Production-oriented entry point"]
        Nginx["Nginx<br/>Ports 80 and 443 configured"]
        Frontend["Next.js Frontend<br/>Port 3000"]
        API["FastAPI REST Gateway<br/>Port 8000"]
        Certbot["Certbot<br/>Certificate management"]
    end

    subgraph App["Application services"]
        Chat["Chat Service<br/>Port 8001"]
        Integrations["Integrations Service<br/>Port 8006"]
        Session["Session Worker"]
        RAG["RAG Worker"]
        User["User Worker"]
    end

    subgraph Infra["Shared infrastructure"]
        PostgreSQL[("PostgreSQL + pgvector")]
        Redis[("Redis")]
        RabbitMQ[("RabbitMQ")]
    end

    Client --> Nginx
    Nginx --> Frontend
    Nginx --> API

    API --> Chat
    API --> Integrations
    API -. "Configured proxy path; verify" .-> Session
    API -. "Configured proxy path; verify" .-> RAG
    API -. "Configured proxy path; verify" .-> User

    Chat --> RabbitMQ
    Session --> RabbitMQ
    RAG --> RabbitMQ
    User --> RabbitMQ

    API --> Redis
    Integrations --> Redis
    API -. "Database access; verify" .-> PostgreSQL

    Certbot -. "Certificate lifecycle" .-> Nginx

    classDef entry fill:#E8F1FE,stroke:#356AC3,color:#172B4D,stroke-width:1.5px
    classDef application fill:#DDF5E5,stroke:#25804B,color:#16452B,stroke-width:1.5px
    classDef infrastructure fill:#FFF2CC,stroke:#B8860B,color:#4D3B00,stroke-width:1.5px
    classDef verification fill:#FCE8E6,stroke:#C5221F,color:#5F1512,stroke-width:1.5px

    class Client,Nginx,Frontend,API entry
    class Chat,Integrations,Session,RAG,User application
    class PostgreSQL,Redis,RabbitMQ infrastructure
    class Certbot verification

    style Edge fill:transparent,stroke:#2563eb,stroke-width:1px
    style App fill:transparent,stroke:#059669,stroke-width:1px
    style Infra fill:transparent,stroke:#B8860B,stroke-width:1px

2. Deployment files¶

Before modifying deployment behavior, inspect the current files and their referenced environment variables. Compose files, Dockerfiles, and application configuration can change independently.

3. Local development deployment¶

3.1 Infrastructure services¶

The inspected local Compose configuration defines the following infrastructure containers.

These are the inspected port mappings, not guarantees of public accessibility or production security. The PostgreSQL image includes pgvector support; actual schema creation, migrations, indexes, and vector-store initialization must be verified separately.

3.2 Application services¶

3.3 Validate and start the stack¶

Run commands from the repository root.

docker compose -f docker-compose.yaml config

docker compose -f docker-compose.yaml up --build -d

docker compose -f docker-compose.yaml ps

3.4 Inspect logs¶

View the latest logs:

docker compose -f docker-compose.yaml logs --tail=200

Follow logs continuously:

docker compose -f docker-compose.yaml logs -f

Inspect a specific service using its actual Compose service name:

docker compose -f docker-compose.yaml logs -f rest_api

Replace rest_api if the service is named differently in the current configuration.

3.5 Stop the development stack¶

Stop containers and remove Compose-managed networks:

docker compose -f docker-compose.yaml down

Named volumes are ordinarily retained. To remove them as well:

docker compose -f docker-compose.yaml down --volumes

4. Startup order and health checks¶

The inspected local Compose configuration declares dependencies between infrastructure and application services.

The exact dependency conditions must be checked against the current Compose file.

Health checks are not readiness guarantees¶

The inspected application health checks use a Python-process check based on /proc/*/cmdline. This establishes process presence, not application readiness.

A running process can still be unable to connect to RabbitMQ, initialize its model, access the database, or process requests.

Recommended improvements:

1. Add explicit health endpoints to HTTP services.
2. Define meaningful readiness checks for RabbitMQ workers.
3. Verify database, Redis, and RabbitMQ connectivity where appropriate.
4. Configure dependent services to react appropriately to failed readiness checks.
5. Test recovery after dependency restarts and temporary outages.

5. Production-oriented deployment¶

5.1 Reverse-proxy routing¶

The inspected docker-compose.prod.yaml includes the frontend, Nginx, and Certbot alongside application and infrastructure services.

The Nginx configuration routes requests to the following upstreams:

The /api/ configuration includes settings intended to support streamed responses, including Server-Sent Events (SSE). Successful streaming must be tested through the deployed reverse proxy.

5.2 Validate production configuration¶

docker compose -f docker-compose.prod.yaml config

docker compose -f docker-compose.prod.yaml ps

Do not start a production deployment until the following have been reviewed:

• Required environment variables are present and correct.
• Registry credentials and image tags are configured.
• Production database and message-broker credentials are unique.
• Persistent storage and backup procedures are defined.
• Services communicate using the correct container-network addresses.
• Nginx upstreams match the deployed service names.
• The frontend uses the intended public API URL.
• Health checks represent actual service readiness.
• Required database migrations and initialization steps are complete.

5.3 Environment variables and secrets¶

The inspected production configuration references variables including:

This is not necessarily the complete environment-variable inventory. Derive the required set from the current Compose files, Dockerfiles, and application configuration.

A successful Compose configuration render does not establish that credentials are valid or external services are reachable.

6. Nginx and HTTPS¶

The inspected Nginx configuration listens on port 80 and declares a server name corresponding to an IP address. The production Compose configuration publishes ports 80 and 443 and defines Certbot with persistent certificate-related volumes.

However, the reviewed Nginx configuration did not establish a complete HTTPS setup: no corresponding listen 443 ssl server block or certificate directives were found.

Before declaring HTTPS operational, verify:

1. The intended domain name and DNS records.
2. The certificate issuance procedure.
3. The ACME challenge route and validation method.
4. The Nginx TLS server block and certificate paths.
5. The HTTP-to-HTTPS redirect policy.
6. Certificate renewal and Nginx reload behavior.
7. Successful external HTTPS requests and certificate validation.

7. Frontend container and API configuration¶

The inspected frontend Dockerfile uses Node.js 20 Alpine, builds the Next.js application using standalone output, exposes port 3000, and starts the application with:

CMD ["node", "server.js"]

The frontend API client uses NEXT_PUBLIC_API_URL, with a development fallback of http://localhost:8000.

Understand the networking boundary¶

For production, verify that:

• The browser requests the intended API origin or relative path.
• Container-to-container traffic uses service names and internal ports.
• The deployed Nginx routes match the frontend's request paths.
• CORS and authentication settings match the actual request flow.
• The frontend is rebuilt when build-time public configuration changes, where required.

8. Development and production differences¶

Maintain explicit configuration boundaries between development and production. Do not rely on development defaults to provide production security.

9. Production security and reliability checklist¶

Use this checklist during deployment review. Record test evidence rather than marking an item complete based solely on configuration inspection.

Configuration and access¶

• Production credentials are unique and stored securely.
• Development credentials are not reused in production.
• Publicly exposed ports are limited to intended entry points.
• PostgreSQL, Redis, and RabbitMQ are not unintentionally exposed to the public internet.
• Container privileges and filesystem permissions have been reviewed.
• The RAG service's root-user configuration has been reviewed for hardening.
• Logs do not expose credentials, tokens, or sensitive user data.

Reliability and recovery¶

• Health checks test meaningful readiness conditions.
• Database and application data have defined backup procedures.
• Backup restoration has been tested.
• Image tags and build inputs are controlled and reproducible.
• Nginx upstreams and request routing have been tested.
• SSE responses work through the reverse proxy.
• HTTPS issuance, configuration, and renewal have been verified.
• Startup ordering and dependency recovery have been tested.
• Deployment and rollback procedures have been documented and tested.

10. Troubleshooting¶

Containers fail to start¶

Inspect service states and logs:

docker compose -f docker-compose.yaml ps
docker compose -f docker-compose.yaml logs --tail=200

Check for missing environment variables, image-build failures, dependency problems, port conflicts, and initialization errors.

A container is running but the application is unavailable¶

A running container does not guarantee readiness. Inspect service logs, health checks, network connectivity, and the actual application entry point.

For Session, RAG, and User, verify RabbitMQ worker behavior rather than assuming their mapped ports provide HTTP endpoints.

Frontend requests fail¶

Verify NEXT_PUBLIC_API_URL, browser network requests, Nginx routing rules, and REST API logs. Establish whether the request originates in the browser or another container.

Message processing fails¶

Inspect RabbitMQ availability, exchange and queue declarations, worker startup logs, credentials, and service-specific configuration. Confirm that publishers and consumers agree on the relevant exchange and queue names.

SSE responses stop or buffer unexpectedly¶

Review the Nginx /api/ location configuration. Test the actual streaming endpoint through the reverse proxy, including long-running responses and connection interruption behavior.

SSE-related directives alone do not prove that streaming works end to end.

HTTPS fails¶

Check DNS, certificate issuance, ACME challenge routing, certificate paths, Nginx TLS configuration, and renewal logs. Publishing port 443 alone does not enable HTTPS.

11. Deployment verification record¶

Complete this table for the actual target environment. Replace each pending status with the observed result and link to relevant test evidence where appropriate.

12. Related documentation¶

• Architecture Overview
• System Design
• Data Flow
• Database Architecture
• Configuration Reference
• Documentation Audit

13. Maintenance policy¶

Update this document whenever Dockerfiles, Compose services, port mappings, dependencies, health checks, environment variables, reverse-proxy routes, certificate configuration, or deployment procedures change.

Keep source-inspected observations separate from verified operational outcomes. A configuration declaration must not be described as a successful test unless recorded evidence demonstrates that the test passed.