​
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

  1. Download Docker Desktop from https://www.docker.com/products/docker-desktop/
  2. Run the installer and follow setup instructions
  3. Enable WSL2 backend (recommended)
  4. 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

  1. Clone the repository.

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

  2. 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

  3. Build the images.

    # Build base image first
docker compose build base

# Build the server and worker
docker compose build

  4. 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

  5. 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!

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

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