Chatwoot Server Deployment Overview¶

Prerequisites¶

The following system parameters and network settings are required for the application to function correctly:

Operating System: Ubuntu or Debian.
Access: Superuser (root) privileges for package installation and Docker management.
Ports:
80 (HTTP) — for initial requests and redirection to HTTPS.
443 (HTTPS) — primary port for application operation via SSL.
3000 (internal) — used by the Rails container.

A dynamic subdomain is used to access the application, following this pattern:

Parameter	Value
Prefix	`chatwoot`
Domain	`hostkey.in`
Full Template	`chatwoot{Server_ID_from_Invapi}.hostkey.in`

All core application components and configuration files are located in the following directory:

/opt/chatwoot — root application directory containing the Docker Compose file and environment variables.
/etc/nginx/sites-available/ — location of Nginx reverse proxy configurations.
/etc/letsencrypt/live/ — directory containing SSL certificates (Certbot).

Deployment is performed by configuring the Docker environment and launching containers via docker compose.

The process includes:

Installing necessary system utilities (curl, git, wget).
Configuring the Docker Engine repository.
Creating the /opt/chatwoot directory and downloading the .env template.
Generating a unique SECRET_KEY_BASE to ensure session security.
Initializing the database using the command: docker compose run --rm rails bundle exec rails db:chatwoot_prepare

Firewall: Ports 80 and 443 must be open.
Data Security:
All passwords for databases (PostgreSQL, Redis) are defined in the .env file.
Forced HTTPS redirection is enabled (FORCE_SSL=true).
Database and internal service ports are bound only to 127.0.0.1, restricting access from outside the server.

The application uses two databases running in isolated containers:

DB Type	Image	Hostname (Docker Network)	Default Password
PostgreSQL	`pgvector/pgvector:pg16`	`postgres`	`chatwoot`
Redis	`redis:alpine`	`redis`	`chatwoot`

Database data is stored in Docker named volumes (postgres_data and redis_data).

The application is deployed using multiple containers. All containers have the always restart policy.

Service Name	Image	Ports (host:container)	Volumes	Environment Variables / Features
`rails`	`chatwoot/chatwoot:latest`	`127.0.0.1:3000:3000`	`storage_data:/app/storage`	`RAILS_ENV=production`, `NODE_ENV=production`
`sidekiq`	`chatwoot/chatwoot:latest`	Not exposed	`storage_data:/app/storage`	Background jobs, `production` mode
`postgres`	`pgvector/pgvector:pg16`	`127.0.0.1:5432:5432`	`postgres_data:/var/lib/postgresql/data`	Configured `chatwoot` DB
`redis`	`redis:alpine`	`127.0.0.1:6379:6379`	`redis_data:/data`	Started with password via command

Updates are performed by pulling new image versions and restarting containers:

docker compose pull && docker compose up -d

Type	Path / Name
Main environment config	`/opt/chatwoot/.env`
Docker Compose file	`/opt/chatwoot/docker-compose.yml`
Nginx configuration	`/etc/nginx/sites-available/{prefix}{server_id}.{zone}`

Only the following ports are available to external users:

All other ports (3000, 5432, 6379) are accessible only locally on the server itself.

Container lifecycle management is performed from the /opt/chatwoot directory:

Start all services:
```
docker compose up -d
```
Stop the application:
```
docker compose down
```
Restart individual components (e.g., Rails):
```
docker compose restart rails sidekiq
```

Nginx is used as the reverse proxy server.

SSL: Certificates are issued via Certbot (Let's Encrypt). Automatic HTTP to HTTPS redirection is configured.
Configuration: Nginx acts as a Reverse Proxy, forwarding traffic from ports 80/443 to the internal Rails container port (127.0.0.1:3000).
Features: The configuration includes support for Upgrade and Connection headers for correct WebSocket operation (via proxy_set_header Upgrade $http_upgrade;).