> ## Documentation Index
> Fetch the complete documentation index at: https://developers.chatwoot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# 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.

```bash theme={null}
make burn
```

This would install all required dependencies for Chatwoot application.

<Warning>
  If you face issue with pg gem, please refer to [Common Errors](/contributing-guide/common-errors#pg-gem-installation-error)
</Warning>

## Setup environment variables

```bash theme={null}
cp .env.example .env
```

Please refer to [environment-variables](/contributing-guide/environment-variables) to read on setting environment variables.

## Setup rails server

```bash theme={null}
# 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.
</Note>

## Login with credentials

```bash theme={null}
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
```

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

```bash theme={null}
bundle exec rails assets:precompile
```

## Docker for development

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

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

```bash theme={null}
# 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](http://localhost:3000)

```bash theme={null}
# 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)

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
docker compose exec rails bundle exec rails assets:precompile
```

Then use the URLs from [#testing-chat-widget-in-your-local-environment](/contributing-guide/project-setup#testing-chat-widget-in-your-local-environment)

### Running Cypress Tests

First,compile the assets. Run:

```bash theme={null}
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://github.com/shakacode/cypress-on-rails)
* [https://docs.cypress.io/guides/overview/why-cypress.html](https://docs.cypress.io/guides/overview/why-cypress.html)

```bash theme={null}
# 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](https://hub.docker.com/r/chatwoot/chatwoot)

```bash theme={null}
docker pull chatwoot/chatwoot
```

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

```bash theme={null}
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](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](/contributing-guide/common-errors)

## Getting Help

If you encounter issues during setup:

* **Common Errors**: Check [Common Errors](/contributing-guide/common-errors)
* **Environment Variables**: See [Environment Variables](/contributing-guide/environment-variables)
* **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
* **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)

***

Your Chatwoot development environment is now ready for contribution! 🚀