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

# 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:

```bash theme={null}
$ 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/](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

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

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

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

## Development Environment

1. **Clone the repository.**

   ```bash theme={null}
   git clone https://github.com/chatwoot/chatwoot.git
   ```

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

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

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

   ```bash theme={null}
   docker compose run --rm rails bundle exec rails db:chatwoot_prepare
   ```

5. **To run the app:**

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

   ```bash theme={null}
   docker compose down
   ```

## Running RSpec Tests

For running the complete RSpec tests:

```bash theme={null}
docker compose run --rm rails bundle exec rspec
```

For running specific test:

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

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

```bash theme={null}
docker compose run --rm --service-port rails
```

## Development Workflow

### Daily Development Commands

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

```bash theme={null}
docker compose down
docker compose build
docker compose run --rm rails bundle exec rails db:reset
docker compose up
```

### Common Issues

<Accordion title="Container fails to start">
  **Solution**: Check service dependencies and logs:

  ```bash theme={null}
  # Check service status
  docker compose ps

  # Check logs for specific service
  docker compose logs rails

  # Restart problematic service
  docker compose restart rails
  ```
</Accordion>

<Accordion title="Database connection refused">
  **Solution**: Ensure PostgreSQL container is healthy:

  ```bash theme={null}
  # Check postgres health
  docker compose exec postgres pg_isready

  # Restart postgres if needed
  docker compose restart postgres
  ```
</Accordion>

<Accordion title="Port already in use">
  **Solution**: Stop other services using the same ports:

  ```bash theme={null}
  # Check what's using port 3000
  lsof -i :3000

  # Or change ports in docker-compose.yaml
  ```
</Accordion>

<Accordion title="Out of disk space">
  **Solution**: Clean up Docker resources:

  ```bash theme={null}
  # Remove unused containers, networks, images
  docker system prune -f

  # Remove volumes (WARNING: This deletes data)
  docker volume prune -f

  # Remove everything (nuclear option)
  docker system prune -a --volumes
  ```
</Accordion>

<Accordion title="Build fails">
  **Solution**: Clear Docker cache and rebuild:

  ```bash theme={null}
  # Clear build cache
  docker builder prune

  # Rebuild without cache
  docker compose build --no-cache
  ```
</Accordion>

## Getting Help

If you encounter Docker-specific issues:

* **Docker Documentation**: [https://docs.docker.com/](https://docs.docker.com/)
* **Docker Compose Reference**: [https://docs.docker.com/compose/](https://docs.docker.com/compose/)
* **Chatwoot Issues**: [GitHub Issues](https://github.com/chatwoot/chatwoot/issues)
* **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)

***

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