Project Setup Guide

Complete guide to setting up and running Chatwoot in development mode

Project Setup

This guide will help you to setup and run Chatwoot in development mode. Please make sure you have completed the environment setup.

Clone the repo

Install Ruby & Javascript dependencies

Use the following command to run bundle && pnpm install to install ruby and Javascript dependencies.

This would install all required dependencies for Chatwoot application.

Setup environment variables

Please refer to environment-variables to read on setting environment variables.

Setup rails server

Login with credentials

Testing chat widget in your local environment

When running Chatwoot in development environment, the chat widget can be accessed under the following URL.

You can also test the setUser method by using

To use those URLs, you first need to compile the assets. Run:

Docker for development

The first time you start your development environment run the following two commands:

Then browse http://localhost:3000

When you change the service's Dockerfile or the contents of the build directory, run stop then build. (For example after modifying package.json or Gemfile)

The docker-compose environment consists of:

• chatwoot server
• postgres
• redis
• webpacker-dev-server

If in case you encounter a seeding issue or you want reset the database you can do it using the following command:

This command essentially runs postgres and redis containers and then run the rake command inside the chatwoot server container.

Testing chat widget in your local environment with Docker

First,compile the assets. Run:

Then use the URLs from #testing-chat-widget-in-your-local-environment

Running Cypress Tests

First,compile the assets. Run:

Running Cypress Tests

Refer the docs to learn how to write cypress specs:

• https://github.com/shakacode/cypress-on-rails
• https://docs.cypress.io/guides/overview/why-cypress.html

Debugging Docker for production

You can use our official Docker image from https://hub.docker.com/r/chatwoot/chatwoot

You can create an image yourselves by running the following command on the root directory.

This will build the image which you can deploy in Kubernetes (GCP, Openshift, AWS, Azure or anywhere), Amazon ECS or Docker Swarm. You can tag this image and push this image to docker registry of your choice.

Remember to make the required environment variables available during the deployment.

Next Steps

After completing this setup:

1. Verify Installation: Access http://localhost:3000 and log in with the provided credentials
2. Explore the Code: Start making changes and see them reflected in your development environment
3. Run Tests: Execute the test suite to ensure everything works correctly
4. Check Troubleshooting: If you encounter issues, refer to Common Errors

Getting Help

If you encounter issues during setup:

• Common Errors: Check Common Errors
• Environment Variables: See Environment Variables
• Discord Community: Join our Discord
• GitHub Issues: Create an issue

Your Chatwoot development environment is now ready for contribution! 🚀