Docker Deployment

Use Docker Compose for a single application replica on one host. For multi-replica or distributed production deployments, use Kubernetes or another orchestrator with shared MongoDB, Redis, and S3-compatible object storage.

Quick Start

# Clone the repository
git clone https://github.com/Yanyutin753/LambChat.git
cd LambChat

# Copy and edit environment file
cp deploy/.env.example .env
# Edit .env with your configuration

# Start all services
docker compose -f deploy/docker-compose.yml up -d

Architecture

Docker Compose starts three services for a single-node stack:

Service	Image	Port	Description
lambchat	Custom build	8000	LambChat application (FastAPI + static frontend)
mongo	mongo:7	27017	MongoDB database
redis	redis:7-alpine	6379	Redis cache & pub/sub

Configuration

Environment Variables

Copy deploy/.env.example to .env and configure:

# Recommended: Set a stable JWT secret (auto-generated on each restart if unset, invalidating existing sessions)
JWT_SECRET_KEY=your-stable-secret-key

# Recommended: Set MCP encryption salt (auto-generated on each restart if unset, invalidating saved MCP configs)
MCP_ENCRYPTION_SALT=your-stable-encryption-salt

# Optional: Configure MongoDB connection
MONGODB_URL=mongodb://localhost:27017
MONGODB_DB=agent_state
MONGODB_USERNAME=admin
MONGODB_PASSWORD=your-mongo-password

# Optional: Configure Redis connection
REDIS_URL=redis://localhost:6379/0
REDIS_PASSWORD=your-redis-password

TIP

LLM models are configured through the Model Config UI after deployment — no environment variables needed. See LLM Configuration for details.

See Environment Variables for the complete reference.

Reverse Proxy

For production, use a reverse proxy (nginx, Traefik, Caddy) with SSL:

nginx example:

server {
    listen 443 ssl http2;
    server_name lambchat.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE support
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
    }
}

When using a reverse proxy, set APP_BASE_URL:

APP_BASE_URL=https://lambchat.example.com

Managing the Stack

# Start services
docker compose -f deploy/docker-compose.yml up -d

# View logs
docker compose -f deploy/docker-compose.yml logs -f lambchat

# Stop services
docker compose -f deploy/docker-compose.yml down

# Restart application (preserves data)
docker compose -f deploy/docker-compose.yml restart lambchat

# Rebuild after code changes
docker compose -f deploy/docker-compose.yml up -d --build lambchat

Data Persistence

Docker Compose uses named volumes for data persistence:

• mongo_data — MongoDB data
• redis_data — Redis data
• uploads — Uploaded files (local storage mode)

These volumes persist across container restarts and recreations.

Do not scale the lambchat Compose service to multiple replicas while using the local uploads volume. Multiple replicas need shared object storage (S3_ENABLED=true) and a load-balanced service without fixed container names or host port conflicts.