Documentation Index
Fetch the complete documentation index at: https://mintlify.com/jAtInn71/chatwoot-costom/llms.txt
Use this file to discover all available pages before exploring further.
Chatwoot Custom ships as a standard Docker Compose stack. This page covers the two ways to get the application image, the full set of environment variables you need to configure, the four services the stack runs, and the commands you’ll use day-to-day.
Image options
Pre-built image
Build locally
The fastest path. Pull the image from Docker Hub — no Node.js, no build time.docker pull jatin4002/chatwoot-custom:latest
docker-compose.yaml in the repository already references this image for both the rails and sidekiq services:image: jatin4002/chatwoot-custom:latest
docker-compose.yaml are needed when you use this image. Run docker compose up -d after setting up your .env file.Use pull_policy: always (already set in the default Compose file) to automatically pull newer tags on each docker compose up.
Use this path if you want to modify the widget code or configure a build-time ElevenLabs agent ID.The build.sh script accepts four optional positional arguments:./build.sh [agent_id] [voice_id] [agent_name] [tag]
| Argument | Default | Description |
|---|
agent_id | agent_6601kc1fqeecfc88s7d52jde0syq | ElevenLabs agent ID baked into the widget bundle |
voice_id | (empty) | ElevenLabs voice ID (optional) |
agent_name | AI Assistant | Display name shown in the widget |
tag | latest | Docker image tag |
# Build with defaults
./build.sh
# Build with a custom agent
./build.sh agent_XXXXXXX voice_YYYYYYY "Support Bot" v1.2.0
docker build with the VITE_ELEVENLABS_AGENT_ID, VITE_ELEVENLABS_VOICE_ID, and VITE_ELEVENLABS_AGENT_NAME build args, then tags the image as chatwoot-custom:<tag>.After building, update the image: line in docker-compose.yaml for both the rails and sidekiq services:image: chatwoot-custom:latest
build: block under those services, and run:The build takes 5–15 minutes and requires 8 GB of free RAM. If it exits with code 139 (SIGSEGV), the Vite bundle ran out of memory. Try closing other applications or use the pre-built image instead.
ElevenLabs agent configuration (agent ID, API key, provider) is now stored per inbox in the dashboard, not as build-time environment variables. The agent_id build argument is a fallback for legacy deployments. For new deployments, leave it at the default and configure voice agents through the dashboard after install.
Environment variables
Copy .env.example to .env and fill in these values before starting the stack:
Required
| Variable | Description |
|---|
FRONTEND_URL | Public URL of the Chatwoot install. Use http://localhost:3000 for local testing. Voice/mic features require HTTPS on public deployments. |
SECRET_KEY_BASE | Long random string for Rails session encryption. Generate with docker run --rm chatwoot/chatwoot:latest rails secret. Never reuse across environments. |
POSTGRES_PASSWORD | Password for the bundled PostgreSQL container. |
REDIS_PASSWORD | Password for the bundled Redis container. Must also appear in REDIS_URL. |
Database
| Variable | Default | Description |
|---|
POSTGRES_DATABASE | chatwoot_prod | Database name |
POSTGRES_USERNAME | chatwoot_prod | Database user |
POSTGRES_HOST | postgres | Hostname of the postgres service (matches the Compose service name) |
POSTGRES_PORT | 5432 | PostgreSQL port |
Redis
| Variable | Description |
|---|
REDIS_URL | Full Redis connection string, e.g. redis://:YOUR_SECURE_REDIS_PASSWORD@redis:6379 |
Rails runtime
| Variable | Default | Description |
|---|
RAILS_ENV | production | Rails environment |
FORCE_SSL | false | Set to true to redirect all HTTP traffic to HTTPS. Requires a valid TLS certificate. |
RAILS_LOG_LEVEL | info | Log verbosity (debug, info, warn, error) |
RAILS_MAX_THREADS | 5 | Puma thread count; also sets the database pool size |
Set FORCE_SSL=true only when your reverse proxy or load balancer handles TLS termination. Enabling it without a valid certificate will make the application unreachable.
Services
The Compose stack runs four services:
| Service | Image | Purpose |
|---|
postgres | pgvector/pgvector:pg14 | Primary database. Includes the pgvector extension for future vector search support. Data persisted to the postgres_data volume. |
redis | redis:7-alpine | Cache and background job queue. Password-protected via REDIS_PASSWORD. Data persisted to the redis_data volume. |
rails | jatin4002/chatwoot-custom:latest | Web application server. Runs db:chatwoot_prepare on startup to apply migrations, then starts Puma on port 3000 (mapped to host port 3001). |
sidekiq | jatin4002/chatwoot-custom:latest | Background job worker. Shares the same image as rails and uses the same .env file. |
rails and sidekiq wait for postgres and redis to pass their health checks before starting.
The rails service is mapped to host port 3001, not 3000. If you’re accessing the dashboard directly (without a reverse proxy), use http://localhost:3001. Set FRONTEND_URL to match.
Useful commands
# Start everything in the background
docker compose up -d
# Stop and remove containers (data volumes are preserved)
docker compose down
# Tail Rails logs
docker compose logs -f rails
# Restart the Rails process after editing mounted volumes
docker compose restart rails
# Open a Rails console
docker compose exec rails rails c
# Open a shell inside the Rails container
docker compose exec rails bash
docker compose logs rails | grep VOICE-AGENT
HTTPS and voice features
Browser microphone access requires a secure context. This means:
http://localhost — works for local development- Any other HTTP origin — microphone blocked by the browser; the voice button will not work
For staging or production, put Chatwoot Custom behind a reverse proxy (nginx, Caddy, Traefik) that terminates TLS, or use a tunnel service such as ngrok or cloudflared. Set FRONTEND_URL to the HTTPS URL and, optionally, set FORCE_SSL=true to redirect HTTP visitors automatically.