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 (Compose reads .env from deploy/)
cp deploy/.env.example deploy/.env
# Edit deploy/.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	ghcr.io/yanyutin753/lambchat:latest	8000	LambChat application (FastAPI + static frontend)
mongodb	mongo:8.2.5	127.0.0.1:27017	MongoDB database
redis	redis:alpine	127.0.0.1:6379	Redis cache & pub/sub

MongoDB and Redis ports are bound to 127.0.0.1 so they are not reachable from other hosts.

Configuration

Environment Variables

Copy deploy/.env.example to deploy/.env. The compose file wires the following variables from it:

# E2B sandbox (optional)
E2B_API_KEY=your_e2b_api_key
E2B_TEMPLATE=base

# Optional tuning
LLM_MODEL_CACHE_SIZE=50
SESSION_MAX_EVENTS_PER_TRACE=10000

REDIS_URL and MONGODB_URL are preset to the in-stack Redis and MongoDB services. Other environment variables such as JWT_SECRET_KEY (stable JWT secret; auto-generated on each restart if unset, invalidating existing sessions) and MCP_ENCRYPTION_SALT (stable MCP encryption salt; auto-generated on each restart if unset, invalidating saved MCP configs) are not wired by default — add them to the environment section of the lambchat service in deploy/docker-compose.yml:

    environment:
      # Recommended: keep sessions valid across restarts
      - JWT_SECRET_KEY=your-stable-secret-key
      # Recommended: keep saved MCP configs decryptable across restarts
      - MCP_ENCRYPTION_SALT=your-stable-encryption-salt

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;
    }
}

File URLs generated within a request automatically follow the entry point the client used (X-Forwarded-Host/Host + X-Forwarded-Proto), so multi-domain deployments need no extra configuration. APP_BASE_URL is only a fallback when no request context exists; it is recommended for URLs generated by background jobs (scheduled-task attachments, message-interception artifacts, etc.):

APP_BASE_URL=https://lambchat.example.com

Upgrade note (connection settings move to env): connection-class settings — database (MONGODB_*/POSTGRES_*/REDIS_*/CHECKPOINT_PG_*), object storage (S3_*) and ENABLE_POSTGRES_STORAGE — are now env-authoritative on startup. Deployments that previously changed these via the settings panel must migrate the values to env/compose and restart; otherwise startup logs an env-authoritative warning and the panel values no longer apply. Behavioral settings in the panel (timeouts, toggles, ...) are unaffected.

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

# Update to the latest published image
docker compose -f deploy/docker-compose.yml pull lambchat
docker compose -f deploy/docker-compose.yml up -d lambchat

Data Persistence

Docker Compose uses named volumes and bind mounts for data persistence:

• mongodb-data — MongoDB data
• redis-data — Redis data
• lamb-data — LambChat application data (/app/data)
• ./workspace — agent workspace (bind mount, resolved under deploy/)
• ./uploads — uploaded files in local storage mode (bind mount, resolved under deploy/)

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.