Skip to main content

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 && yarn 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

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

Login with credentials​

http://localhost:3000
user name: john@acme.inc
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

Docker for development​

Note: 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.

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
yarn 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 depoy 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.