Chatwoot

Replace <vm-ip> with the public IP of your VM. The default login user is azureuser.

ssh azureuser@<vm-ip>

sudo systemctl is-active docker.service nginx.service chatwoot.service docker --version docker compose version

You should see active printed three times, the Docker Engine version, and the Docker Compose v2 plugin version.

sudo docker ps --format "table {{.Names}}\t{{.Status}}"

You should see all four containers in the Up state: chatwoot-rails-1, chatwoot-sidekiq-1, chatwoot-postgres-1 and chatwoot-redis-1.

All stateful Chatwoot data lives on a dedicated data disk mounted at /var/lib/chatwoot.

findmnt /var/lib/chatwoot df -h /var/lib/chatwoot

findmnt shows the device backing /var/lib/chatwoot, and df confirms the 40 GiB volume.

The nginx reverse proxy serves an unauthenticated static /health endpoint on port 80. The Chatwoot API answers on /api.

curl -s http://localhost/health
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/api

/health returns OK and /api returns 200. Together they confirm that nginx and the Rails app are both up.

On its first boot, your instance generates a unique super admin email and password and writes them to a root-only file.

sudo cat /root/chatwoot-credentials.txt

This file lists CHATWOOT_URL (where to sign in), CHATWOOT_ADMIN_EMAIL and CHATWOOT_ADMIN_PASSWORD. Store the password somewhere safe.

Open http://<vm-ip>/ in your browser. You are redirected to the agent sign-in page. Enter the CHATWOOT_ADMIN_EMAIL and CHATWOOT_ADMIN_PASSWORD from Step 6, then sign in.

You can also verify the login from the command line with the Devise Token Auth endpoint. A correct password returns 200:

EMAIL=$(sudo grep '^CHATWOOT_ADMIN_EMAIL=' /root/chatwoot-credentials.txt | cut -d= -f2-)
PASS=$(sudo grep '^CHATWOOT_ADMIN_PASSWORD=' /root/chatwoot-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost/auth/sign_in \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASS\"}"

A 200 confirms that the per-VM super admin authenticates end to end.

After you sign in, you land on the conversations dashboard. This is the shared team inbox where live chat, email and social conversations arrive and are assigned to agents.

From the dashboard, you can manage your contacts directory:

You can also review conversation analytics and configure your account from the reports and settings area:

Chatwoot organises incoming conversations into inboxes. From the agent dashboard, open Settings, then Inboxes, then Add Inbox. Choose a channel, for example a Website live-chat widget, an email channel or an API channel.

Follow the wizard to name the inbox. Then embed the generated widget script in your website, or connect your channel. New conversations from that channel appear in the dashboard for your agents.

Open the product page in AWS Marketplace and choose Continue to Subscribe. Accept the terms, then choose Continue to Configuration and Continue to Launch.

Pick your Region, the m5.large instance type, your VPC and public subnet, and your key pair. Choose a security group that allows inbound 22 and 80, as above. Then launch the instance.

aws ec2 run-instances \
  --image-id <ami-id-from-the-listing> \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids sg-xxxxxxxx \
  --subnet-id subnet-xxxxxxxx \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=chatwoot-01}]'

Chatwoot serves an unauthenticated readiness endpoint at /health through nginx. Poll it until it returns 200. That signals that first boot has finished and the agent inbox is reachable.

curl -s -o /dev/null -w "GET /health -> HTTP %{http_code}\n" http://127.0.0.1/health

GET /health -> HTTP 200

Confirm that the four systemd units the appliance depends on are active:

systemctl is-active chatwoot.service nginx.service docker.service

active active active

Then confirm that the four containers of the stack are running on the pinned release:

sudo docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

NAMES IMAGE STATUS chatwoot-rails-1 chatwoot/chatwoot:v4.16.1 Up 2 minutes chatwoot-sidekiq-1 chatwoot/chatwoot:v4.16.1 Up 2 minutes chatwoot-redis-1 redis:alpine Up 2 minutes chatwoot-postgres-1 pgvector/pgvector:pg16 Up 2 minutes

No login is baked into the image. First boot generates a random administrator password for this instance alone. It writes the password, together with the account email and the instance URL, to a root-only file:

sudo cat /root/chatwoot-credentials.txt

The file contains a CHATWOOT_URL, a CHATWOOT_ADMIN_EMAIL and a CHATWOOT_ADMIN_PASSWORD. Copy the password into your password manager and treat the file as a secret. It is mode 0600 and owned by root.

Without leaving the shell, you can confirm that the credential is genuinely per instance and that a wrong password is rejected:

sudo grep -c '^CHATWOOT_ADMIN_PASSWORD=' /root/chatwoot-credentials.txt

1

Browse to http://<instance-public-ip>/ and sign in with the email and password from the credentials file.

After you sign in, you land on the agent dashboard. The conversation list is on the left, the shared inbox navigation runs down the side, and the getting-started cards are on the right.

Once you are in, change the administrator password from Profile Settings and store the new one in your password manager.

An inbox is a channel that Chatwoot receives conversations from. Go to Settings, then Inboxes, and choose Add Inbox to pick a channel.

For a website live chat widget, choose Website. Give the inbox a name and your site's domain, then finish the wizard. Chatwoot generates a small JavaScript snippet. Paste it before the closing </body> tag of your site, and the widget appears for your visitors. Conversations started in the widget arrive in the inbox you just created.

Other channels available in this image include Email (connect a mailbox over IMAP/SMTP), WhatsApp, SMS via Twilio, Telegram, Line and a generic API channel for building your own integration. Channels that require a third-party developer application, such as Facebook and Instagram, need those credentials configured before you can select them.

Go to Settings, then Agents, and choose Add Agent to invite a colleague by email address. Each person can be given the Agent or Administrator role. Under Settings, then Teams, you can group agents so that conversations are routed to a team rather than an individual.

Account self-signup is disabled in this image, so people cannot create their own accounts on your instance. Add agents from this screen instead.

Outbound email is not configured out of the box. Agent invitation emails and notification emails are not delivered until you add SMTP settings (see Step 9).

Reports gives live conversation and agent metrics. These include open, unattended, unassigned and pending conversation counts, agent availability, and conversation traffic and resolutions over time. It also provides per-agent, per-label, per-inbox, per-team, CSAT and SLA breakdowns.

Scope each report by date range and inbox. Download it as CSV using the download control on the panel.

Chatwoot needs an SMTP relay to send agent invitations, password resets, notifications and email-channel replies. Add your provider's settings to the environment file and restart the stack.

The environment file at /opt/chatwoot/.env holds the application configuration. List the setting names it currently defines. Never print the file itself, because it contains your database and cache passwords:

sudo grep -Eo '^[A-Z_]+=' /opt/chatwoot/.env | tr -d '=' | sort | head -20

ACTIVE_STORAGE_SERVICE ENABLE_ACCOUNT_SIGNUP FORCE_SSL FRONTEND_URL INSTALLATION_ENV LOG_LEVEL NODE_ENV POSTGRES_DATABASE POSTGRES_HOST POSTGRES_PASSWORD POSTGRES_PORT POSTGRES_USERNAME RAILS_ENV RAILS_LOG_TO_STDOUT REDIS_PASSWORD REDIS_URL SECRET_KEY_BASE

Append your SMTP configuration to /opt/chatwoot/.env with your editor of choice, then restart. For example, set SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD and MAILER_SENDER_EMAIL:

Task Command

Edit the environment file sudo nano /opt/chatwoot/.env

Restart Chatwoot after editing sudo systemctl restart chatwoot

The Chatwoot environment variable reference documents the exact variable names for your provider. Keep the file at mode 0600, because it holds your database and cache passwords as well.

The database, the cache and every uploaded attachment live on a dedicated EBS volume mounted at /var/lib/chatwoot. It is separate from the OS root volume, so you can resize or snapshot it independently:

df -h /var/lib/chatwoot | tail -1

/dev/nvme1n1 40G 75M 37G 1% /var/lib/chatwoot

The volume is mounted by filesystem UUID from /etc/fstab, so it survives reboots and instance-type changes:

grep chatwoot /etc/fstab

To grow it, expand the EBS volume in the AWS console or CLI. Then extend the filesystem on the instance with sudo resize2fs /dev/nvme1n1, substituting the device name reported by lsblk. No downtime is required.

Take an EBS snapshot of the data volume for a whole-appliance restore point. Also dump the database for a portable logical backup:

sudo docker exec chatwoot-postgres-1 pg_dump -U postgres chatwoot | gzip > ~/chatwoot-backup.sql.gz

Check that the dump was written with ls -lh ~/chatwoot-backup.sql.gz. Store the dump off the instance, for example in Amazon S3. Keep it alongside a snapshot of /var/lib/chatwoot, which holds the uploaded attachments.

The only service published on the instance's network interface is nginx on port 80. The Rails application, PostgreSQL and Redis are all bound to the loopback interface. They cannot be reached from outside the instance, even if your security group is wide open:

sudo ss -tlnp | grep -E ':80 |:3000 |:5432 |:6379 ' | awk '{print $1, $4}'

LISTEN 127.0.0.1:5432 LISTEN 127.0.0.1:6379 LISTEN 0.0.0.0:80 LISTEN 127.0.0.1:3000 LISTEN [::]:80

Recommended hardening:

• Restrict 22/tcp in the security group to your management network only.
• Restrict 80/tcp to the networks your agents use, if your live chat widget is used only internally.
• Terminate TLS in front of Chatwoot (see Step 13), so agent credentials and customer conversations are encrypted in transit.
• Enable EBS encryption on the data volume for encryption at rest.
• Change the seeded administrator password after first sign-in, and add named agent accounts rather than sharing it.

Chatwoot is served over plain HTTP on port 80 out of the box, so the appliance is reachable immediately after launch. For production use, put it behind TLS. There are two supported approaches:

Terminate TLS on an AWS Application Load Balancer. Point an ALB at the instance on port 80, attach an AWS Certificate Manager certificate, and put your DNS record on the ALB. Then set the public URL that Chatwoot advertises:

Task Command

Set the public URL sudo sed -i 's#^FRONTEND_URL=.*#FRONTEND_URL=https://chat.example.com/#' /opt/chatwoot/.env

Apply the change sudo systemctl restart chatwoot

Or terminate TLS on the instance with Let's Encrypt. Point a DNS A record at the instance's public address. Then install certbot and let it configure the existing nginx site:

Task Command

Install certbot sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx

Issue and install the certificate sudo certbot --nginx -d chat.example.com

Set the public URL sudo sed -i 's#^FRONTEND_URL=.*#FRONTEND_URL=https://chat.example.com/#' /opt/chatwoot/.env

Apply the change sudo systemctl restart chatwoot

Certbot installs a renewal timer automatically. Make sure 443/tcp is open in the security group before you issue the certificate.

Task Command

Start Chatwoot sudo systemctl start chatwoot

Stop Chatwoot sudo systemctl stop chatwoot

Restart Chatwoot sudo systemctl restart chatwoot

Application logs sudo docker logs -f chatwoot-rails-1

Background worker logs sudo docker logs -f chatwoot-sidekiq-1

Reverse proxy status systemctl status nginx

First-boot log sudo journalctl -u chatwoot-firstboot -n 100

Check the running container set at any time with:

sudo docker compose -f /opt/chatwoot/docker-compose.yml ps --format '{{.Name}} {{.State}}'