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

# change location to the path you want chatwoot to be installed
cd ~

# clone the repo and cd to chatwoot dir
git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot

Install Ruby & Javascript dependencies

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

make burn

This would install all required dependencies for Chatwoot application.

If you face issue with pg gem, please refer to Common Errors

Setup environment variables

cp .env.example .env

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

Setup rails server

# run db migrations
make db
# fireup the server
foreman start -f Procfile.dev

If you have overmind installed, use make run to run the server.

Login with credentials

http://localhost:3000
user name: [e-mail]
password: Password1!

Testing chat widget in your local environment

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

http://localhost:3000/widget_tests

You can also test the setUser method by using

http://localhost:3000/widget_tests?setUser=true

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

bundle exec rails assets:precompile

Docker for development

Follow this section only if you are trying to setup Chatwoot via docker. Else skip this.

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

# build base image first
docker compose build base

# build the server and worker
docker compose build

# prepare the database
docker compose exec rails bundle exec rails db:chatwoot_prepare

# docker compose up

Then browse http://localhost:3000

# To stop your environment use Control+C (on Mac) CTRL+C (on Win) or
docker compose down
# start the services
docker compose up

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)

docker compose stop
docker compose build

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:

docker compose run --rm rails bundle exec rake db:reset

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:

docker compose exec rails bundle exec rails assets:precompile

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

Running Cypress Tests

First,compile the assets. Run:

docker compose exec rails bundle exec rails assets:precompile

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

# in terminal tab1
overmind start -f Procfile.test
# in terminal tab2
pnpm cypress open --project ./test

Debugging Docker for production

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

docker pull chatwoot/chatwoot

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

docker compose -f docker-compose.production.yaml build

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! 🚀