181 lines
4.8 KiB
Plaintext
181 lines
4.8 KiB
Plaintext
---
|
|
title: Project Setup Guide
|
|
description: Complete guide to setting up and running Chatwoot in development mode
|
|
sidebarTitle: Setup Guide
|
|
---
|
|
|
|
# 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
|
|
# 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
|
|
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/project-setup/common-errors#pg-gem-installation-error)
|
|
</Warning>
|
|
|
|
## Setup environment variables
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Please refer to [environment-variables](/contributing/project-setup/environment-variables) to read on setting environment variables.
|
|
|
|
## Setup rails server
|
|
|
|
```bash
|
|
# 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
|
|
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.
|
|
</Note>
|
|
|
|
The first time you start your development environment run the following two commands:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
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
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
docker pull chatwoot/chatwoot
|
|
```
|
|
|
|
You can create an image yourselves by running the following command on the root directory.
|
|
|
|
```bash
|
|
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](/contributing/project-setup/common-errors)
|
|
|
|
## Getting Help
|
|
|
|
If you encounter issues during setup:
|
|
|
|
- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
|
|
- **Environment Variables**: See [Environment Variables](/contributing/project-setup/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! 🚀 |