chatwoot/developer-docs/contributing/project-setup/docker-setup.mdx

---
title: Docker Development Setup
description: Complete guide to setting up Chatwoot development environment using Docker and Docker Compose.
sidebarTitle: Docker Setup
---

# 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
$ 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
# 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
# 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
    git clone https://github.com/chatwoot/chatwoot.git
    ```

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

    ```bash
    # 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
    # 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
    docker compose run --rm rails bundle exec rails db:chatwoot_prepare
    ```

5. **To run the app:**

    ```bash
    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
    docker compose down
    ```

## Running RSpec Tests

For running the complete RSpec tests:

```bash
docker compose run --rm rails bundle exec rspec
```

For running specific test:

```bash
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
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
docker compose run --rm --service-port rails
```

## Development Workflow

### Daily Development Commands

```bash
# 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
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
# 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
# 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
# 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
# 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
# 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! 🐳