add intro documentation and user guide
This commit is contained in:
Tanmay Deep Sharma
@@ -0,0 +1,283 @@
|
||||
---
|
||||
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! 🐳
|
||||
Reference in New Issue
Block a user