chatwoot/chatwoot installation guide

Installing Chatwoot on macOS Tahoe (Apple silicon)

What this repository is

Chatwoot is a self-hosted customer-support platform. Its README describes a shared inbox for channels such as website chat, email, Facebook, Instagram, WhatsApp, Telegram, Line, and SMS. It also includes help-center publishing, contact management, automation, reports, integrations, and an AI support agent called Captain.

This is a large Ruby web application, not a normal Mac app that you drag into **Applications**. The supplied first-party files document hosted deployment links, but they do **not** provide a complete local-development or production-install procedure for macOS. In particular, they do not document the required Ruby, Node.js, PostgreSQL, Redis, or package-manager versions, nor do they provide source-supported commands for cloning, preparing, migrating, or starting Chatwoot locally.

Because commands and requirements must not be invented, this guide uses the repository’s documented **Heroku one-click deployment**. That route runs Chatwoot on Heroku rather than directly on your Apple-silicon Mac, so macOS Tahoe and processor architecture do not create a documented compatibility issue. Your Mac is used to open the deployment pages and complete Chatwoot’s browser-based onboarding.

Relationship to Claude Code

**Classification: unclassified.**

The supplied repository metadata and first-party files do not show a Claude Code plugin, hook, skill, MCP server, rules file, command package, or other reliable Claude Code integration mechanism. Chatwoot does contain an AI support feature named Captain, but that is part of the customer-support product and is not evidence that the repository extends Claude Code. Do not install this repository expecting it to add capabilities to Claude Code.

Before you begin

Have the following information ready:

• Your name.
• Your company or organization name.
• A work email address.
• A password of at least six characters. The onboarding page explicitly displays that minimum.
• The configuration values required for the Chatwoot features you intend to use.

The README warns that relevant environment variables must be set and that features may break when they are omitted. It points to the first-party environment-variable documentation at:

<https://www.chatwoot.com/docs/environment-variables>

Review that page before deploying. The supplied repository files do not include the variable list, so this guide cannot safely reproduce names, values, or defaults. Treat passwords, API keys, signing secrets, and service credentials as sensitive. Do not paste them into public issues, screenshots, or shared notes.

For a stable installation, use the repository’s `master` branch or a version tag labeled `v1.x.x`. The README says that `develop` is the base development branch and recommends `master` or those tags for stable use. Conveniently, the documented Heroku deployment link already targets `master`.

Recommended installation: Heroku one-click deployment

1. Open the official deployment link

On your Mac, open Safari or another browser and visit the Heroku deployment link published in Chatwoot’s README:

<https://heroku.com/deploy?template=https://github.com/chatwoot/chatwoot/tree/master>

Confirm that the template URL shown in the address points to `github.com/chatwoot/chatwoot/tree/master`. This keeps you on the stable branch recommended by the repository rather than the `develop` branch listed as the repository default.

2. Follow Heroku’s deployment flow

The Chatwoot README describes this as a one-click deployment, but the supplied files do not document Heroku’s current screens, account requirements, pricing, region choices, generated resource names, or button labels. Follow the prompts Heroku presents without relying on invented field-by-field directions.

Before approving the deployment, compare any configuration fields with Chatwoot’s official environment-variable page. Set the variables relevant to the channels and features you plan to operate. Do not assume that an empty field is safe merely because the deployment form permits it: Chatwoot explicitly warns that missing relevant variables can cause breakage.

Complete the provider’s deployment flow and wait for it to report its result. If Heroku reports a failure, retain the exact error text and consult Chatwoot’s detailed documentation at:

<https://www.chatwoot.com/help-center>

The repository also links a deployment overview for other supported options:

<https://chatwoot.com/deploy>

This guide does not recommend speculative Terminal fixes because no Heroku troubleshooting commands were supplied in the evidence.

3. Open the deployed Chatwoot site

Use the application address produced by the hosting flow. A fresh installation can show Chatwoot’s onboarding page, headed **“Howdy, Welcome to Chatwoot.”** The first-party onboarding view asks for:

1. **Name** — your full name.
2. **Company Name** — the account or organization name.
3. **Work Email** — the initial administrator’s email address.
4. **Password** — at least six characters, according to the displayed placeholder.

The corresponding controller creates the account and initial user as a confirmed super administrator. Use an email address and password you are authorized to use, and store the password securely.

4. Decide whether to subscribe

The onboarding form includes a checkbox labeled **“Subscribe to release notes, newsletters & product feedback surveys.”** It is selected by default in the supplied view.

The controller shows an important consequence: when the checkbox remains selected, Chatwoot calls its instance-registration service with the company name, user name, and email address. When it is cleared, that registration call is skipped. Choose deliberately based on your organization’s privacy and communications preferences.

After reviewing the entries and checkbox, select **Finish Setup**. Successful onboarding removes the installation-onboarding flag and redirects to the application. If account creation fails, the page redirects with an error and leaves onboarding available for another attempt.

Verify the installation

After setup, confirm that you can reach the Chatwoot interface and sign in with the administrator account you just created. Verify only the capabilities you actually configured. The README describes many optional channels and integrations, but their presence in the product description does not mean each one is automatically operational.

A sensible verification pass is to check that:

• The application page loads without an installation error.
• The initial administrator can access the account.
• The company name and user identity match what you entered.
• Features relying on environment variables behave as expected.
• Any external channel or integration you intentionally configured connects successfully.

Do not use production customer data merely to test an uncertain setup. Chatwoot’s security policy specifically says security testing should be performed against a self-hosted instance and not against Chatwoot production services.

Alternative documented deployment

The README also offers a **DigitalOcean 1-Click Kubernetes deployment**:

<https://marketplace.digitalocean.com/apps/chatwoot?refcode=f2238426a2a8>

Use this only if you deliberately want the DigitalOcean Kubernetes option. The supplied files do not document its cluster requirements, billing, configuration screens, upgrade process, or Terminal commands, so those details cannot be safely expanded here. Chatwoot’s deployment page is the appropriate first-party starting point for comparing supported hosts.

What not to do on your Mac

Do not treat the commands in `tests/playwright/README.md` as a Chatwoot application installer. They install dependencies and browser components for the end-to-end test suite, copy a test environment template, and run tests against an already available Chatwoot instance. They do not document how to create or start the underlying application.

Similarly, do not improvise a Homebrew, Docker, Ruby, Rails, PostgreSQL, Redis, or source-build procedure from general knowledge. Although repository metadata includes topics such as Docker, Rails, and Ruby, topics are not installation instructions. No complete, macOS-Tahoe-specific local procedure was supplied.

Maintenance and security

The security policy states that only the **latest** version is supported; versions older than latest are not. Plan for ongoing updates using whichever supported hosting path you selected, and consult current first-party documentation before making changes. The supplied evidence does not provide source-supported update, backup, rollback, or uninstall commands, so none should be invented.

If you discover a security vulnerability, do not open a public GitHub issue or post it on social media. Use Chatwoot’s private GitHub advisory form:

<https://github.com/chatwoot/chatwoot/security/advisories/new>

Questions about the disclosure process can be sent to `security@chatwoot.com`, but the policy asks that actual disclosures use the private GitHub form.

At this point, the documented installation is complete: Chatwoot is deployed on the selected hosted platform, and its initial super-administrator account has been created through the onboarding page. A native or local Apple-silicon installation cannot be responsibly documented from the supplied first-party evidence.