Deployment Overview of Chatwoot on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the server must meet the following requirements:

Operating System: Ubuntu or Debian.
Privileges: Root or sudo access is required for package installation and service management.
Domain: A valid domain name is required for SSL termination via Certbot.
Ports:
80/TCP: For HTTP traffic and Let's Encrypt validation.
443/TCP: For secure HTTPS traffic.
3000/TCP: Internal application port (accessible locally).

The application is accessible via a specific subdomain template based on the server ID.

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

The application files and data are organized in the following locations:

/opt/chatwoot/: Main application directory containing configuration and orchestration files.
/etc/nginx/sites-available/: Nginx site configuration templates.
/etc/nginx/sites-enabled/: Active Nginx symbolic links.
/etc/letsencrypt/live/: SSL certificates managed by Certbot.

The installation is performed using a combination of system package management and Docker orchestration:

System Preparation: The process begins by updating the local package index and installing essential dependencies including ca-certificates, curl, git, and wget.
Docker Engine Setup: The official Docker repository is added to the system, and docker-ce along with the docker-compose-plugin are installed. The Docker service is enabled and started automatically.
Environment Configuration:
A directory at /opt/chatwoot is created.
An environment file (.env) is downloaded from the official Chatwoot repository.
Critical settings such as FRONTEND_URL, ENABLE_ACCOUNT_SIGNUP, and database passwords are injected into the .env file.
A unique SECRET_KEY_BASE is generated to secure application sessions.
Database Initialization: The system runs a one-time command via Docker Compose to prepare the database schema (db:chatwoot_prepare).
Service Orchestration: The application containers are started in detached mode using docker compose up -d.
Web Server Configuration: Nginx is installed and configured as a reverse proxy to forward traffic from port 80/443 to the internal application port 3000.

Firewall: The system relies on standard web ports (80, 443) being open.
SSL/TLS: SSL certificates are obtained via Certbot using Let's Encrypt. Automatic redirection from HTTP to HTTPS is configured in Nginx.
Internal Networking: Docker containers communicate over an internal network; sensitive ports like 5432 (Postgres) and 6379 (Redis) are bound only to the local loopback interface (127.0.0.1) to prevent external access.

The application utilizes two primary database services running in Docker containers:

The application is composed of several containers defined in /opt/chatwoot/docker-compose.yml:

Service	Image	Ports	Volumes	Restart Policy
`rails`	`chatwoot/chatwoot:latest`	`127.0.0.1:3000:3000`	`storage_data:/app/storage`	always
`sidekiq`	`chatwoot/chatwoot:latest`	N/A	`storage_data:/app/storage`	always
`postgres`	`pgvector/pgvector:pg16`	`127.0.0.1:5432:5432`	`postgres_data:/var/lib/postgresql/data`	always
`redis`	`redis:alpine`	`127.0.0.1:6379:6379`	`redis_data:/data`	always

Database Preparation: A command is executed via docker compose run --rm rails bundle exec rails db:chatwoot_prepare to initialize the database schema before the main services start.
Environment Variable Injection: The installation process dynamically updates the .env file to ensure FRONTEND_URL uses the correct HTTPS protocol and that FORCE_SSL is enabled for security.

To update the Chatwoot application, navigate to the application directory and execute:

cd /opt/chatwoot
docker compose pull && docker compose up -d

The application is managed via Docker Compose from the /opt/chatwoot directory.

To start the application:

docker compose up -d

To stop the application:

docker compose down

To restart specific services (e.g., Rails or Sidekiq):

docker compose restart rails sidekiq