Docker Development Setup

Complete guide to setting up Chatwoot development environment using Docker and Docker Compose.

Docker Development Setup

This guide will help you set up a complete Chatwoot development environment using Docker and Docker Compose.

Pre-requisites

Before proceeding, make sure you have the latest version of docker and docker-compose installed.

As of now, we recommend a version equal to or higher than the following:

$ docker --version
Docker version 25.0.4, build 1a576c5
$ docker compose --version
docker-compose version 2.24.7

Install Docker

Windows

Download Docker Desktop from https://www.docker.com/products/docker-desktop/
Run the installer and follow setup instructions
Enable WSL2 backend (recommended)
Restart your computer when prompted

macOS

# Option 1: Download from website
# Go to https://www.docker.com/products/docker-desktop/

# Option 2: Using Homebrew
brew install --cask docker

Linux (Ubuntu/Debian)

# Update package index
sudo apt update

# Install dependencies
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add Docker repository
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add user to docker group
sudo usermod -aG docker $USER

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

After adding yourself to the docker group on Linux, log out and log back in for the changes to take effect.

Development Environment

Clone the repository.

git clone https://github.com/chatwoot/chatwoot.git

Make a copy of the example environment file and modify it as required.

# Navigate to Chatwoot
cd chatwoot
cp .env.example .env
# Update redis and postgres passwords
nano .env
# Update docker-compose.yaml with the same postgres password
nano docker-compose.yaml

Build the images.

# Build base image first
docker compose build base

# Build the server and worker
docker compose build

After building the image or destroying the stack, you would have to reset the database using the following command.
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
To run the app:
docker compose up
- Access the rails app frontend by visiting http://0.0.0.0:3000/
- Access Mailhog inbox by visiting http://0.0.0.0:8025/ (You will receive all emails going out of the application here)
Login with credentials
url: http://localhost:3000
user_name: john@acme.inc
password: Password1!
To stop the app:
docker compose down

Running RSpec Tests

For running the complete RSpec tests:

docker compose run --rm rails bundle exec rspec

For running specific test:

docker compose run --rm rails bundle exec rspec spec/<path-to-file>:<line-number>

Production Environment

To debug the production build locally, set SECRET_KEY_BASE environment variable in your .env file and then run the below commands:

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

Debugging Mode

To use debuggers like byebug or binding.pry, use the following command to bring up the app instead of docker compose up:

docker compose run --rm --service-port rails

Development Workflow

Daily Development Commands

# Start development environment
docker compose up

# View logs
docker compose logs -f rails

# Access Rails console
docker compose exec rails bundle exec rails console

# Run migrations
docker compose exec rails bundle exec rails db:migrate

# Install new gems
docker compose exec rails bundle install

# Restart a service
docker compose restart rails

# Stop all services
docker compose down

# Stop and remove volumes (reset database)
docker compose down -v

Troubleshooting

If there is an update to any of the following:

dockerfile
gemfile
package.json
schema change

Make sure to rebuild the containers and run db:reset.

docker compose down
docker compose build
docker compose run --rm rails bundle exec rails db:reset
docker compose up

Common Issues

Getting Help

If you encounter Docker-specific issues:

Docker Documentation: https://docs.docker.com/
Docker Compose Reference: https://docs.docker.com/compose/
Chatwoot Issues: GitHub Issues
Community Support: Discord

Your Docker development environment is now ready for Chatwoot development! 🐳

Windows Development Setup Make Commands Setup

Built with

Show your support! Star us on GitHub ⭐️

Star

Docker Development Setup

Complete guide to setting up Chatwoot development environment using Docker and Docker Compose.

Docker Development Setup

Pre-requisites

Install Docker

Windows

macOS

Linux (Ubuntu/Debian)

Development Environment

Login with credentials

Running RSpec Tests

Production Environment

Debugging Mode

Development Workflow

Daily Development Commands

Troubleshooting

Common Issues

Getting Help