Configuration Reference¶

This reference describes the configuration baseline currently observed for WhiteLotusAI. It covers configuration sources, service addresses, environment-specific settings, validation procedures, and security expectations for local development and production deployment.

The goal is to make configuration changes predictable, reviewable, and maintainable without embedding secrets in source code or documentation.

1. Configuration principles¶

WhiteLotusAI configuration should follow these principles:

1. Separate environments. Use distinct, explicitly configured values for development and production.
2. Keep secrets out of source control. Do not commit passwords, API keys, OAuth client secrets, refresh tokens, signing keys, or encryption keys.
3. Validate required settings. Services should fail clearly when required configuration is missing or invalid.
4. Avoid silent production fallbacks. Development defaults must not become production configuration accidentally.
5. Use internal service addresses inside the container network. Container-to-container calls should use the appropriate service hostname and container port.
6. Document ownership. Record which component consumes each setting and why it exists.
7. Verify behavior, not just declarations. A variable in a Compose file is not proof that the application reads or uses it as intended.

2. Configuration lifecycle¶

Use the following workflow when investigating or changing a setting. The diagram describes the recommended verification process; it is not a claim that every service implements a single shared configuration loader.

flowchart TD
    A["Configuration source"] --> B["Find the declaration"]
    B --> C["Trace every consumer"]
    C --> D["Check defaults and validation"]
    D --> E{"Build-time or runtime?"}
    E -->|"Build-time"| F["Rebuild the affected image"]
    E -->|"Runtime"| G["Update environment and restart as needed"]
    F --> H["Validate and test"]
    G --> H
    H --> I["Review logs, health checks, and application behavior"]
    I --> J["Update this reference"]

    %% Node fill and text use the active Mermaid theme for light/dark compatibility.
    %% Colored outlines distinguish lifecycle stages without hard-coding fills or text colors.
    classDef source stroke:#2563eb,stroke-width:2px
    classDef discovery stroke:#7c3aed,stroke-width:2px
    classDef validation stroke:#059669,stroke-width:2px
    classDef decision stroke:#d97706,stroke-width:2.5px
    classDef action stroke:#64748b,stroke-width:1.5px
    classDef maintenance stroke:#0d9488,stroke-width:2px

    class A source
    class B,C discovery
    class D,H validation
    class E decision
    class F,G,I action
    class J maintenance

For each configuration variable, establish:

• Where it is declared and where it is read.
• Which service consumes it.
• Whether it is required or optional.
• Whether a default exists and whether that default is safe in production.
• Whether it is used at build time, runtime, or both.
• Whether the application validates it.
• Whether a change requires an image rebuild, a container restart, or both.

Avoid undocumented duplicate values across multiple configuration files.

3. Configuration sources¶

The inspected repository includes the following configuration sources. Confirm their presence and current contents in the active checkout before making changes.

4. Configuration by component¶

4.1 Frontend¶

The frontend is a Next.js application. The inspected API client defines its base URL as follows:

const BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:8000";

The frontend constructs API requests under /api/....

For production, configure the frontend to use the intended browser-accessible API origin or the appropriate relative path, based on how the application constructs its requests.

Next.js public environment variables can be embedded in the client bundle during the build. Verify how the Docker build receives NEXT_PUBLIC_API_URL; do not assume that changing a container environment variable after the frontend bundle has been built will update that bundle.¹

4.2 REST API gateway¶

The REST API is implemented with FastAPI and listens on port 8000 in the inspected configuration.

Observed behavior includes:

• A Redis-backed rate limiter is initialized during application startup.
• CORS origins are derived from settings.ALLOWED_HOSTS.
• API documentation endpoints are enabled only in development according to the inspected application entry point.
• The gateway communicates with internal application services through HTTP and RabbitMQ-based service calls.

Confirm the exact required environment variables for Redis, CORS, authentication, database access, and messaging against the REST API settings implementation.

Do not assume that ALLOWED_HOSTS has the same meaning as a similarly named setting in another framework. Verify how this project's CORS configuration consumes the value and how it is parsed.

4.3 Internal service URLs¶

The following internal HTTP service URLs were observed in the inspected configuration:

These are internal container-network addresses, not necessarily public endpoints. The inspected Chat configuration also uses the RAG, User, and Integrations service URLs. The REST API proxy resolves internal service URLs for supported request paths.

When changing a service address, review callers, Compose service names, container ports, network configuration, and health checks together.

4.4 RabbitMQ¶

RabbitMQ provides inter-service messaging. The local Compose configuration uses this development connection string:

amqp://guest:guest@rabbitmq:5672/

This development default must not be reused in production.

The inspected code references the following exchanges:

The shared communication implementation uses RabbitMQ request/reply messaging, including reply queues and correlation IDs.

Verify the exact environment-variable names for RabbitMQ credentials, connection URLs, queue names, and exchange names against current settings modules. Do not assume the observed exchange names are independently configurable unless the implementation confirms this.

For production:

• Use dedicated credentials with appropriate permissions.
• Keep credentials out of committed files.
• Confirm publishers and consumers use compatible exchange and queue declarations.
• Test behavior during broker restarts and temporary connection failures.
• Do not expose the management interface publicly without a documented requirement and appropriate access controls.

4.5 PostgreSQL and pgvector¶

The local Compose configuration uses the pgvector/pgvector:pg16 image. The inspected host mapping is 5433:5432: the database container listens on port 5432, while the host exposes it on port 5433.

Use an address appropriate to the caller:

• A process running on the host can use the configured host mapping.
• A container on the same Compose network should normally use the PostgreSQL service name and container port.

The production Compose configuration references POSTGRES_USER and POSTGRES_PASSWORD.

The complete database configuration inventory, schema ownership, migration mechanism, and list of components that open database connections directly have not been established by this reference. Verify these details against the database settings and initialization code.

4.6 Redis¶

Redis 7 is used by the local Compose configuration. The inspected REST API initializes a Redis-backed rate limiter, and the Integrations service depends on Redis.

Confirm the complete Redis configuration contract against the service settings and connection code, including:

• Connection URL and authentication.
• Database index and timeout behavior.
• Reconnection and failure behavior.
• Production persistence requirements, where applicable.

Do not assume every service uses Redis for the same purpose merely because Redis is available on the Compose network.

4.7 Integrations and OAuth¶

The Integrations service contains integration, webhook, MCP, and OAuth-related routes. The inspected Gmail client also sends an HTTP request to the User service when persisting a refreshed token.

OAuth configuration may involve provider-specific client identifiers, client secrets, redirect URIs, access tokens, and refresh tokens.

For provider credentials and OAuth flows:

• Keep secrets outside committed configuration.
• Use the redirect URI registered for the correct environment.
• Separate development and production OAuth applications where appropriate.
• Never log authorization codes, access tokens, refresh tokens, or client secrets.
• Confirm token encryption, storage, refresh, and revocation behavior.
• Verify that token-persistence calls reach an actual server and a mounted endpoint.

The inspected User application entry point starts a RabbitMQ listener. The existence of an OAuth-related router in the codebase does not, by itself, prove the User process exposes its HTTP endpoints. Verify route mounting and the server arrangement before relying on token-persistence behavior.

4.8 Encryption configuration¶

The inspected User worker invokes assert_encryption_key() during startup. This indicates that encryption configuration is important to the User service's initialization.

Before documenting the exact encryption variable or algorithm, inspect the implementation that defines the key, validates it, and performs encryption or decryption.

Production requirements:

• Generate a cryptographically strong key in the format required by the application.
• Store it in an approved secrets-management system.
• Never commit the key or paste it into documentation, issue trackers, or logs.
• Ensure every component that must decrypt stored data uses the correct key.
• Define a controlled rotation and recovery process.
• Understand the impact of key loss before deploying encryption-dependent storage.

Do not replace an existing encryption key casually. Previously encrypted data may become unreadable if the application does not support key rotation or multiple active keys.

5. Environment-specific configuration¶

6. Safe configuration validation¶

6.1 Validate Compose configuration¶

Run these commands from the repository root. They validate Compose configuration syntax and interpolation; they do not prove application behavior or deployment readiness.

docker compose -f docker-compose.yaml config --quiet

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

If a command fails because a required variable is missing, identify the variable in the relevant configuration and supply the intended value through the appropriate environment-specific mechanism.

6.2 Inspect environment-variable references¶

From the repository root, use the following search as a discovery aid:

rg -n 'os\.getenv|os\.environ|BaseSettings|SettingsConfigDict|load_dotenv|process\.env|env_file|environment:' \
  --glob '*.py' \
  --glob '*.ts' \
  --glob '*.tsx' \
  --glob '*.js' \
  --glob '*.yaml' \
  --glob '*.yml' \
  --glob '*.toml' \
  --glob '!.venv/**' \
  --glob '!node_modules/**'

Review the results manually. This search is not a complete inventory: configuration may be loaded indirectly, declared in other formats, or passed through helper functions. Do not share unredacted output if it includes credentials or secret values.

7. Secret-management requirements¶

Treat the following as sensitive configuration:

• LLM provider API keys.
• Database passwords.
• RabbitMQ credentials.
• OAuth client secrets.
• OAuth access and refresh tokens.
• Encryption keys.
• Signing keys and session secrets.
• Any credential used to access an external service.

Required practices:

1. Keep actual secrets out of tracked source files and documentation.
2. Use placeholders in example files.
3. Restrict production secret access to the services and people that need it.
4. Rotate exposed or potentially compromised credentials.
5. Review Git history when a credential has previously been committed.
6. Remove credentials from current tracked files, while recognizing that deletion does not erase Git history.
7. Avoid printing secret values in application logs, shell output, or diagnostic reports.
8. Verify .gitignore rules are effective; ignore rules do not remove files that are already tracked.
9. Use a documented process for secret rotation and recovery.

8. Configuration change procedure¶

Use this process whenever a configuration variable, endpoint, credential, or deployment setting changes:

1. Identify the setting's declaration and every consumer.
2. Determine whether it is a build-time value, runtime value, or both.
3. Update the relevant example and environment-specific configuration.
4. Check that the change does not introduce a secret into source control.
5. Validate Compose and application settings.
6. Rebuild affected images if build-time configuration changed.
7. Restart or redeploy affected services as required.
8. Test the relevant application flow.
9. Review logs and health checks for startup or connection errors.
10. Update this document if the configuration contract changed.

Avoid changing several unrelated settings at once while troubleshooting. Smaller, isolated changes make failures easier to identify.

9. Configuration inventory completion checklist¶

Use this checklist to finish and maintain the full configuration inventory.

• Enumerate all variables declared in the Compose files.
• Enumerate application settings for REST API, Chat, Session, RAG, User, and Integrations components.
• Record the exact environment-variable name for each setting.
• Record its owning service, purpose, required/optional status, and default.
• Identify secrets and document only their storage mechanism—not their values.
• Verify environment-variable parsing and validation.
• Verify the frontend API URL in local and production builds.
• Verify RabbitMQ exchange, queue, and connection configuration.
• Verify PostgreSQL and Redis connection settings.
• Verify OAuth and encryption settings.
• Confirm each documented HTTP endpoint is served by a running HTTP application.
• Test startup behavior when a required variable is missing.
• Confirm production credentials differ from development credentials.
• Review previously committed credentials and complete necessary rotations.

10. Related documentation¶

• Architecture Overview
• System Design
• Data Flow
• Database Architecture
• Docker Deployment
• Documentation Audit

11. Maintenance policy¶

Update this reference whenever configuration variables, service URLs, authentication mechanisms, infrastructure dependencies, environment-loading behavior, or deployment requirements change.

Do not record secret values in this document. Clearly distinguish verified configuration behavior from assumptions and items still requiring investigation. Consider the reference complete only after its variable inventory has been checked against the current source code and deployment configuration.