add intro documentation and user guide
This commit is contained in:
Tanmay Deep Sharma
@@ -991,9 +991,7 @@ What you expected to happen
|
||||
What actually happened
|
||||
|
||||
## Error Messages
|
||||
```
|
||||
Full error message and stack trace
|
||||
```
|
||||
|
||||
## Additional Context
|
||||
Any other relevant information
|
||||
|
||||
@@ -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! 🐳
|
||||
@@ -8,651 +8,10 @@ sidebarTitle: Environment Variables
|
||||
|
||||
This guide covers environment variables specifically for development and testing environments. For production environment variables, see the [Self-hosted Environment Variables](../../self-hosted/configuration/environment-variables) guide.
|
||||
|
||||
## Development Environment Setup
|
||||
### Use letter opener instead of mailhog/SMTP
|
||||
|
||||
### Basic Development Configuration
|
||||
|
||||
Create your `.env` file from the example:
|
||||
Set the following variable to open emails in letter opener instead of SMTP
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### Essential Development Variables
|
||||
|
||||
```bash
|
||||
# Rails Environment
|
||||
RAILS_ENV=development
|
||||
NODE_ENV=development
|
||||
|
||||
# Application Configuration
|
||||
FRONTEND_URL=http://localhost:3000
|
||||
FORCE_SSL=false
|
||||
SECRET_KEY_BASE=your-secret-key-here
|
||||
|
||||
# Database Configuration
|
||||
DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
|
||||
# Development Features
|
||||
ENABLE_DEVELOPMENT_FEATURES=true
|
||||
RAILS_LOG_LEVEL=debug
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
## Database Configuration
|
||||
|
||||
### PostgreSQL Settings
|
||||
|
||||
```bash
|
||||
# Primary database connection
|
||||
DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_development
|
||||
|
||||
# Alternative format (individual variables)
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_USERNAME=chatwoot
|
||||
DB_PASSWORD=password
|
||||
DB_NAME=chatwoot_development
|
||||
|
||||
# Test database
|
||||
TEST_DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_test
|
||||
```
|
||||
|
||||
### Redis Configuration
|
||||
|
||||
```bash
|
||||
# Redis connection for development
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
|
||||
# Redis with authentication
|
||||
REDIS_URL=redis://:password@localhost:6379/0
|
||||
|
||||
# Redis Sentinel (for advanced setups)
|
||||
REDIS_SENTINELS=localhost:26379
|
||||
REDIS_SENTINEL_MASTER_NAME=mymaster
|
||||
|
||||
# Sidekiq Redis (can be separate)
|
||||
SIDEKIQ_REDIS_URL=redis://localhost:6379/1
|
||||
```
|
||||
|
||||
## Email Configuration for Development
|
||||
|
||||
### Local Email Testing
|
||||
|
||||
```bash
|
||||
# MailHog configuration (recommended for development)
|
||||
MAILER_SENDER_EMAIL=dev@chatwoot.local
|
||||
SMTP_ADDRESS=localhost
|
||||
SMTP_PORT=1025
|
||||
SMTP_DOMAIN=chatwoot.local
|
||||
SMTP_ENABLE_STARTTLS_AUTO=false
|
||||
SMTP_TLS=false
|
||||
|
||||
# Alternative: Letter Opener (emails open in browser)
|
||||
LETTER_OPENER=true
|
||||
```
|
||||
|
||||
### Gmail SMTP (for testing real emails)
|
||||
|
||||
```bash
|
||||
MAILER_SENDER_EMAIL=your-email@gmail.com
|
||||
SMTP_ADDRESS=smtp.gmail.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=your-email@gmail.com
|
||||
SMTP_PASSWORD=your-app-password
|
||||
SMTP_DOMAIN=gmail.com
|
||||
SMTP_ENABLE_STARTTLS_AUTO=true
|
||||
SMTP_TLS=true
|
||||
```
|
||||
|
||||
### Mailtrap (for testing)
|
||||
|
||||
```bash
|
||||
MAILER_SENDER_EMAIL=dev@chatwoot.local
|
||||
SMTP_ADDRESS=smtp.mailtrap.io
|
||||
SMTP_PORT=2525
|
||||
SMTP_USERNAME=your-mailtrap-username
|
||||
SMTP_PASSWORD=your-mailtrap-password
|
||||
SMTP_DOMAIN=chatwoot.local
|
||||
```
|
||||
|
||||
## File Storage Configuration
|
||||
|
||||
### Local Storage (Default for Development)
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE=local
|
||||
```
|
||||
|
||||
### AWS S3 for Development
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE=amazon
|
||||
AWS_ACCESS_KEY_ID=your-access-key
|
||||
AWS_SECRET_ACCESS_KEY=your-secret-key
|
||||
AWS_REGION=us-east-1
|
||||
AWS_BUCKET_NAME=chatwoot-dev-bucket
|
||||
```
|
||||
|
||||
### Google Cloud Storage
|
||||
|
||||
```bash
|
||||
ACTIVE_STORAGE_SERVICE=google
|
||||
GCS_PROJECT_ID=your-project-id
|
||||
GCS_CREDENTIALS=path/to/credentials.json
|
||||
GCS_BUCKET=chatwoot-dev-bucket
|
||||
```
|
||||
|
||||
## Development Features
|
||||
|
||||
### Debug and Logging
|
||||
|
||||
```bash
|
||||
# Enable development features
|
||||
ENABLE_DEVELOPMENT_FEATURES=true
|
||||
|
||||
# Logging levels
|
||||
RAILS_LOG_LEVEL=debug
|
||||
LOG_LEVEL=debug
|
||||
SIDEKIQ_LOG_LEVEL=debug
|
||||
|
||||
# SQL query logging
|
||||
ACTIVE_RECORD_VERBOSE_QUERY_LOGS=true
|
||||
|
||||
# Bullet gem for N+1 query detection
|
||||
BULLET_ENABLED=true
|
||||
```
|
||||
|
||||
### Performance Monitoring
|
||||
|
||||
```bash
|
||||
# Enable query analysis
|
||||
QUERY_ANALYSIS=true
|
||||
|
||||
# Memory profiling
|
||||
MEMORY_PROFILER=true
|
||||
|
||||
# Rack Mini Profiler
|
||||
RACK_MINI_PROFILER=true
|
||||
|
||||
# Benchmark mode
|
||||
BENCHMARK_MODE=true
|
||||
```
|
||||
|
||||
### Code Quality Tools
|
||||
|
||||
```bash
|
||||
# RuboCop configuration
|
||||
RUBOCOP_PARALLEL=true
|
||||
|
||||
# Coverage reporting
|
||||
COVERAGE=true
|
||||
SIMPLECOV_FORMATTER=html
|
||||
|
||||
# Test environment
|
||||
RSPEC_RETRY_COUNT=3
|
||||
PARALLEL_TEST_PROCESSORS=4
|
||||
```
|
||||
|
||||
## Testing Environment Variables
|
||||
|
||||
### Test Database Configuration
|
||||
|
||||
```bash
|
||||
# Test environment
|
||||
RAILS_ENV=test
|
||||
|
||||
# Test database
|
||||
TEST_DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_test
|
||||
|
||||
# Test Redis
|
||||
TEST_REDIS_URL=redis://localhost:6379/15
|
||||
|
||||
# Disable external services in tests
|
||||
DISABLE_EXTERNAL_HTTP=true
|
||||
MOCK_EXTERNAL_SERVICES=true
|
||||
```
|
||||
|
||||
### Test-Specific Settings
|
||||
|
||||
```bash
|
||||
# Faster tests
|
||||
RAILS_ENV=test
|
||||
DISABLE_SPRING=true
|
||||
PARALLEL_WORKERS=4
|
||||
|
||||
# Test coverage
|
||||
COVERAGE=true
|
||||
COVERAGE_REPORTS=true
|
||||
|
||||
# Selenium/Capybara configuration
|
||||
SELENIUM_REMOTE_URL=http://localhost:4444/wd/hub
|
||||
CAPYBARA_SERVER_PORT=3001
|
||||
HEADLESS_CHROME=true
|
||||
|
||||
# Factory Bot settings
|
||||
FACTORY_BOT_ALLOW_CLASS_LOOKUP=false
|
||||
```
|
||||
|
||||
## Integration Testing
|
||||
|
||||
### External Service Mocking
|
||||
|
||||
```bash
|
||||
# Mock external APIs
|
||||
MOCK_FACEBOOK_API=true
|
||||
MOCK_TWITTER_API=true
|
||||
MOCK_WHATSAPP_API=true
|
||||
MOCK_TELEGRAM_API=true
|
||||
|
||||
# Webhook testing
|
||||
WEBHOOK_TEST_URL=http://localhost:3000/webhooks/test
|
||||
NGROK_TUNNEL_URL=https://your-tunnel.ngrok.io
|
||||
```
|
||||
|
||||
### API Testing
|
||||
|
||||
```bash
|
||||
# API testing configuration
|
||||
API_TEST_TOKEN=test-token-123
|
||||
API_TEST_ACCOUNT_ID=1
|
||||
API_TEST_USER_ID=1
|
||||
|
||||
# Rate limiting (disabled for tests)
|
||||
RATE_LIMITING_ENABLED=false
|
||||
```
|
||||
|
||||
## Development Tools
|
||||
|
||||
### Code Analysis
|
||||
|
||||
```bash
|
||||
# Brakeman security scanner
|
||||
BRAKEMAN_ENABLED=true
|
||||
|
||||
# Bundle audit
|
||||
BUNDLE_AUDIT_ENABLED=true
|
||||
|
||||
# Reek code smell detector
|
||||
REEK_ENABLED=true
|
||||
|
||||
# Rails Best Practices
|
||||
RAILS_BEST_PRACTICES_ENABLED=true
|
||||
```
|
||||
|
||||
### Development Servers
|
||||
|
||||
```bash
|
||||
# Webpack dev server
|
||||
WEBPACK_DEV_SERVER_HOST=localhost
|
||||
WEBPACK_DEV_SERVER_PORT=3035
|
||||
|
||||
# Hot module replacement
|
||||
HMR_ENABLED=true
|
||||
|
||||
# Live reload
|
||||
LIVE_RELOAD=true
|
||||
```
|
||||
|
||||
## Third-Party Integrations (Development)
|
||||
|
||||
### Social Media (Test Credentials)
|
||||
|
||||
```bash
|
||||
# Facebook (use test app credentials)
|
||||
FB_APP_ID=your-test-app-id
|
||||
FB_APP_SECRET=your-test-app-secret
|
||||
FB_VERIFY_TOKEN=test-verify-token
|
||||
|
||||
# Twitter (use test credentials)
|
||||
TWITTER_APP_ID=your-test-app-id
|
||||
TWITTER_CONSUMER_KEY=your-test-consumer-key
|
||||
TWITTER_CONSUMER_SECRET=your-test-consumer-secret
|
||||
|
||||
# WhatsApp (use test credentials)
|
||||
WHATSAPP_VERIFY_TOKEN=test-verify-token
|
||||
```
|
||||
|
||||
### Push Notifications (Development)
|
||||
|
||||
```bash
|
||||
# FCM (use development project)
|
||||
FCM_SERVER_KEY=your-dev-server-key
|
||||
FCM_PROJECT_ID=your-dev-project-id
|
||||
|
||||
# Vapid keys for web push
|
||||
VAPID_PUBLIC_KEY=your-dev-public-key
|
||||
VAPID_PRIVATE_KEY=your-dev-private-key
|
||||
```
|
||||
|
||||
## Security Settings for Development
|
||||
|
||||
### Authentication
|
||||
|
||||
```bash
|
||||
# JWT settings
|
||||
JWT_SECRET_KEY=your-dev-jwt-secret
|
||||
JWT_EXPIRY=24h
|
||||
|
||||
# Session configuration
|
||||
SESSION_TIMEOUT=1440
|
||||
SECURE_COOKIES=false
|
||||
|
||||
# CORS settings (permissive for development)
|
||||
CORS_ORIGINS=http://localhost:3000,http://localhost:3001
|
||||
```
|
||||
|
||||
### Development Security
|
||||
|
||||
```bash
|
||||
# Disable security features for development
|
||||
FORCE_SSL=false
|
||||
SECURE_HEADERS=false
|
||||
CSP_ENABLED=false
|
||||
|
||||
# Allow insecure connections
|
||||
ALLOW_HTTP=true
|
||||
SKIP_SSL_VERIFICATION=true
|
||||
```
|
||||
|
||||
## Environment-Specific Configurations
|
||||
|
||||
### Development Environment
|
||||
|
||||
```bash
|
||||
# .env.development
|
||||
RAILS_ENV=development
|
||||
NODE_ENV=development
|
||||
CACHE_CLASSES=false
|
||||
EAGER_LOAD=false
|
||||
CONSIDER_ALL_REQUESTS_LOCAL=true
|
||||
ACTION_CONTROLLER_PERFORM_CACHING=false
|
||||
```
|
||||
|
||||
### Test Environment
|
||||
|
||||
```bash
|
||||
# .env.test
|
||||
RAILS_ENV=test
|
||||
NODE_ENV=test
|
||||
CACHE_CLASSES=true
|
||||
EAGER_LOAD=false
|
||||
PUBLIC_FILE_SERVER_ENABLED=true
|
||||
SHOW_EXCEPTIONS=false
|
||||
```
|
||||
|
||||
### Staging Environment
|
||||
|
||||
```bash
|
||||
# .env.staging
|
||||
RAILS_ENV=staging
|
||||
NODE_ENV=production
|
||||
FORCE_SSL=true
|
||||
LOG_LEVEL=info
|
||||
RAILS_SERVE_STATIC_FILES=true
|
||||
```
|
||||
|
||||
## Docker Development
|
||||
|
||||
### Docker Compose Variables
|
||||
|
||||
```bash
|
||||
# Docker-specific configuration
|
||||
POSTGRES_HOST=postgres
|
||||
POSTGRES_PORT=5432
|
||||
POSTGRES_USER=postgres
|
||||
POSTGRES_PASSWORD=postgres
|
||||
POSTGRES_DB=chatwoot
|
||||
|
||||
REDIS_HOST=redis
|
||||
REDIS_PORT=6379
|
||||
|
||||
# Rails configuration for Docker
|
||||
RAILS_ENV=development
|
||||
RAILS_MAX_THREADS=5
|
||||
WEB_CONCURRENCY=2
|
||||
```
|
||||
|
||||
### Development with Docker
|
||||
|
||||
```bash
|
||||
# Use Docker services
|
||||
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/chatwoot_development
|
||||
REDIS_URL=redis://redis:6379/0
|
||||
|
||||
# File permissions (for volume mounts)
|
||||
DOCKER_USER_ID=1000
|
||||
DOCKER_GROUP_ID=1000
|
||||
```
|
||||
|
||||
## IDE and Editor Configuration
|
||||
|
||||
### VS Code Settings
|
||||
|
||||
```bash
|
||||
# Ruby LSP configuration
|
||||
RUBY_LSP_ENABLED=true
|
||||
RUBY_LSP_EXPERIMENTAL_FEATURES=true
|
||||
|
||||
# Solargraph configuration
|
||||
SOLARGRAPH_ENABLED=true
|
||||
```
|
||||
|
||||
### RubyMine Settings
|
||||
|
||||
```bash
|
||||
# RubyMine-specific settings
|
||||
RUBYMINE_PROJECT_ROOT=/path/to/chatwoot
|
||||
RUBYMINE_RUBY_VERSION=3.3.3
|
||||
```
|
||||
|
||||
## Performance and Monitoring
|
||||
|
||||
### Development Monitoring
|
||||
|
||||
```bash
|
||||
# New Relic (development license)
|
||||
NEW_RELIC_LICENSE_KEY=your-dev-license-key
|
||||
NEW_RELIC_APP_NAME=Chatwoot Development
|
||||
|
||||
# Sentry (development DSN)
|
||||
SENTRY_DSN=your-dev-sentry-dsn
|
||||
SENTRY_ENVIRONMENT=development
|
||||
|
||||
# DataDog (development)
|
||||
DD_API_KEY=your-dev-datadog-key
|
||||
DD_ENV=development
|
||||
```
|
||||
|
||||
### Memory and Performance
|
||||
|
||||
```bash
|
||||
# Memory settings
|
||||
RUBY_GC_HEAP_INIT_SLOTS=10000
|
||||
RUBY_GC_HEAP_FREE_SLOTS=10000
|
||||
RUBY_GC_HEAP_GROWTH_FACTOR=1.1
|
||||
|
||||
# Puma configuration
|
||||
PUMA_WORKERS=1
|
||||
PUMA_THREADS=5
|
||||
PUMA_PRELOAD_APP=false
|
||||
```
|
||||
|
||||
## Common Development Scenarios
|
||||
|
||||
### API Development
|
||||
|
||||
```bash
|
||||
# API-specific settings
|
||||
API_RATE_LIMIT=1000
|
||||
API_RATE_LIMIT_WINDOW=3600
|
||||
API_PAGINATION_LIMIT=100
|
||||
|
||||
# CORS for API development
|
||||
API_CORS_ORIGINS=http://localhost:3001,http://localhost:8080
|
||||
```
|
||||
|
||||
### Widget Development
|
||||
|
||||
```bash
|
||||
# Widget development
|
||||
WIDGET_BASE_URL=http://localhost:3000
|
||||
WIDGET_API_URL=http://localhost:3000/api/v1
|
||||
WIDGET_WS_URL=ws://localhost:3000/cable
|
||||
```
|
||||
|
||||
### Mobile App Development
|
||||
|
||||
```bash
|
||||
# Mobile API endpoints
|
||||
MOBILE_API_URL=http://localhost:3000/api/v1
|
||||
MOBILE_WS_URL=ws://localhost:3000/cable
|
||||
|
||||
# Push notification testing
|
||||
MOBILE_PUSH_ENABLED=true
|
||||
```
|
||||
|
||||
## Troubleshooting Environment Issues
|
||||
|
||||
### Common Environment Problems
|
||||
|
||||
<Accordion title="Database connection issues">
|
||||
**Problem**: `ActiveRecord::ConnectionNotEstablished`
|
||||
|
||||
**Check these variables**:
|
||||
```bash
|
||||
DATABASE_URL=postgresql://username:password@localhost:5432/chatwoot_development
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
```
|
||||
|
||||
**Verify connection**:
|
||||
```bash
|
||||
psql $DATABASE_URL -c "SELECT 1;"
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Redis connection issues">
|
||||
**Problem**: `Redis::CannotConnectError`
|
||||
|
||||
**Check these variables**:
|
||||
```bash
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
```
|
||||
|
||||
**Verify connection**:
|
||||
```bash
|
||||
redis-cli -u $REDIS_URL ping
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Email delivery issues">
|
||||
**Problem**: Emails not being sent in development
|
||||
|
||||
**Check these variables**:
|
||||
```bash
|
||||
MAILER_SENDER_EMAIL=dev@chatwoot.local
|
||||
SMTP_ADDRESS=localhost
|
||||
SMTP_PORT=1025
|
||||
```
|
||||
|
||||
**For MailHog**:
|
||||
```bash
|
||||
# Start MailHog
|
||||
mailhog
|
||||
|
||||
# Check web interface at http://localhost:8025
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Asset compilation issues">
|
||||
**Problem**: `Webpacker::Manifest::MissingEntryError`
|
||||
|
||||
**Check these variables**:
|
||||
```bash
|
||||
NODE_ENV=development
|
||||
RAILS_ENV=development
|
||||
```
|
||||
|
||||
**Recompile assets**:
|
||||
```bash
|
||||
pnpm run dev
|
||||
# or
|
||||
bundle exec rails assets:precompile
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
### Environment Validation
|
||||
|
||||
Create a script to validate your environment:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate_env.sh
|
||||
|
||||
echo "Validating development environment..."
|
||||
|
||||
# Check required variables
|
||||
required_vars=(
|
||||
"RAILS_ENV"
|
||||
"DATABASE_URL"
|
||||
"REDIS_URL"
|
||||
"SECRET_KEY_BASE"
|
||||
"FRONTEND_URL"
|
||||
)
|
||||
|
||||
for var in "${required_vars[@]}"; do
|
||||
if [ -z "${!var}" ]; then
|
||||
echo "❌ Missing required variable: $var"
|
||||
else
|
||||
echo "✅ $var is set"
|
||||
fi
|
||||
done
|
||||
|
||||
# Test database connection
|
||||
if bundle exec rails runner "ActiveRecord::Base.connection.execute('SELECT 1')" > /dev/null 2>&1; then
|
||||
echo "✅ Database connection successful"
|
||||
else
|
||||
echo "❌ Database connection failed"
|
||||
fi
|
||||
|
||||
# Test Redis connection
|
||||
if bundle exec rails runner "Redis.new.ping" > /dev/null 2>&1; then
|
||||
echo "✅ Redis connection successful"
|
||||
else
|
||||
echo "❌ Redis connection failed"
|
||||
fi
|
||||
|
||||
echo "Environment validation complete!"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Environment File Management
|
||||
|
||||
1. **Never commit `.env` files** to version control
|
||||
2. **Use `.env.example`** as a template for required variables
|
||||
3. **Document all variables** with comments
|
||||
4. **Use different `.env` files** for different environments
|
||||
5. **Validate environment** before starting development
|
||||
|
||||
### Security Considerations
|
||||
|
||||
1. **Use weak credentials** only in development
|
||||
2. **Never use production credentials** in development
|
||||
3. **Rotate test API keys** regularly
|
||||
4. **Use local services** when possible
|
||||
5. **Mock external services** in tests
|
||||
|
||||
### Performance Tips
|
||||
|
||||
1. **Use local Redis** for faster development
|
||||
2. **Enable query caching** in development
|
||||
3. **Use parallel testing** for faster test runs
|
||||
4. **Profile memory usage** regularly
|
||||
5. **Monitor database queries** for N+1 issues
|
||||
|
||||
---
|
||||
|
||||
This guide covers the essential environment variables for Chatwoot development. For production deployment, refer to the [Self-hosted Environment Variables](../../self-hosted/configuration/environment-variables) guide.
|
||||
```
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
@@ -0,0 +1,198 @@
|
||||
---
|
||||
title: Line App Integration Setup
|
||||
description: Setup Line app integration on your local machine for development
|
||||
sidebarTitle: Line Setup
|
||||
---
|
||||
|
||||
# Setup Line app integration on your local machine
|
||||
|
||||
Please follow the steps if you are trying to work with the Line integration on your local machine.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Line Developer Account
|
||||
- Access to [Line Developer Console](https://developers.line.biz/console)
|
||||
- Ngrok or similar tunneling service
|
||||
- Running Chatwoot development environment
|
||||
|
||||
## Setup Steps
|
||||
|
||||
### 1. Start Ngrok Server
|
||||
|
||||
Start a Ngrok server listening at port `3000` or the port you will be running the Chatwoot installation:
|
||||
|
||||
```bash
|
||||
# Install ngrok if you haven't already
|
||||
# Download from https://ngrok.com/download
|
||||
|
||||
# Start ngrok tunnel
|
||||
ngrok http 3000
|
||||
```
|
||||
|
||||
### 2. Update Environment Variables
|
||||
|
||||
Update the `.env` variable `FRONTEND_URL` in Chatwoot with the `https` version of the Ngrok URL:
|
||||
|
||||
```bash
|
||||
# In your .env file
|
||||
FRONTEND_URL=https://your-ngrok-subdomain.ngrok.io
|
||||
```
|
||||
|
||||
### 3. Configure Line Developer Console
|
||||
|
||||
1. **Access Line Developer Console**: Go to [Line Developer Console](https://developers.line.biz/console)
|
||||
2. **Create a Provider** (if you don't have one)
|
||||
3. **Create a New Channel** and select "Messaging API"
|
||||
4. **Configure Basic Settings**:
|
||||
- Channel name
|
||||
- Channel description
|
||||
- Category
|
||||
- Subcategory
|
||||
|
||||
### 4. Get Required Credentials
|
||||
|
||||
From the Line Developer Console under the "Messaging API" channel, collect the following values:
|
||||
|
||||
1. **Channel Name**
|
||||
2. **LINE Channel ID**
|
||||
3. **LINE Channel Secret**
|
||||
4. **LINE Channel Token**
|
||||
|
||||
### 5. Start Chatwoot Server
|
||||
|
||||
Start the Chatwoot server and create a new Line channel with the values obtained from Line Developer Console:
|
||||
|
||||
```bash
|
||||
# Start the development server
|
||||
make run
|
||||
# or
|
||||
foreman start -f Procfile.dev
|
||||
```
|
||||
|
||||
### 6. Create Line Channel in Chatwoot
|
||||
|
||||
1. **Access Chatwoot**: Go to your Chatwoot instance (http://localhost:3000)
|
||||
2. **Navigate to Settings** → **Inboxes** → **Add Inbox**
|
||||
3. **Select Line** as the channel type
|
||||
4. **Enter Line Credentials**:
|
||||
- Channel Name
|
||||
- LINE Channel ID
|
||||
- LINE Channel Secret
|
||||
- LINE Channel Token
|
||||
5. **Save Configuration**
|
||||
|
||||
## Configure Webhook in Line Developer Console
|
||||
|
||||
After creating the channel, Chatwoot will provide a webhook URL for the channel. You need to configure this webhook URL in the Line Developer Console:
|
||||
|
||||
### Steps to Configure Webhook
|
||||
|
||||
1. **Go to Line Developer Console** → Your Channel → **Messaging API**
|
||||
2. **Find Webhook Settings**
|
||||
3. **Set Webhook URL**: Use the URL provided by Chatwoot
|
||||
```
|
||||
https://your-ngrok-subdomain.ngrok.io/webhooks/line/your-channel-id
|
||||
```
|
||||
4. **Enable Webhook**: Toggle the webhook to "Enabled"
|
||||
5. **Verify Webhook**: Use the "Verify" button to test the connection
|
||||
|
||||
### Additional Line Settings
|
||||
|
||||
Configure these settings in the Line Developer Console:
|
||||
|
||||
- **Auto-reply messages**: Disable (so Chatwoot can handle responses)
|
||||
- **Greeting messages**: Optional
|
||||
- **Webhook redelivery**: Enable for reliability
|
||||
|
||||
## Testing the Integration
|
||||
|
||||
If the webhook is registered correctly with Line, your Ngrok server should receive events for new Line messages, and new conversations will be created in Chatwoot.
|
||||
|
||||
### Test Steps
|
||||
|
||||
1. **Add your Line bot as a friend** using the QR code or bot ID
|
||||
2. **Send a message** to your Line bot
|
||||
3. **Check Ngrok logs** to see if the webhook request is received
|
||||
4. **Check Chatwoot** to see if a new conversation is created
|
||||
5. **Reply from Chatwoot** to test bidirectional communication
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Accordion title="Webhook verification fails">
|
||||
**Problem**: Line webhook verification fails in Developer Console
|
||||
|
||||
**Solution**:
|
||||
- Ensure your Ngrok URL is accessible publicly
|
||||
- Check that `FRONTEND_URL` is set correctly in your `.env` file
|
||||
- Verify the webhook URL format is correct
|
||||
- Restart Chatwoot after updating environment variables
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Messages not appearing in Chatwoot">
|
||||
**Problem**: Line messages don't create conversations in Chatwoot
|
||||
|
||||
**Solution**:
|
||||
- Check Ngrok logs for incoming webhook requests
|
||||
- Verify webhook is enabled in Line Developer Console
|
||||
- Check Chatwoot logs for any error messages
|
||||
- Ensure all Line credentials are entered correctly
|
||||
- Verify the channel is enabled in Chatwoot
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="SSL/TLS errors">
|
||||
**Problem**: SSL certificate issues with webhook
|
||||
|
||||
**Solution**:
|
||||
- Use the `https` version of your Ngrok URL
|
||||
- Ensure Ngrok is running properly
|
||||
- Line requires HTTPS for webhook URLs
|
||||
- Try restarting Ngrok and updating the webhook
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Authentication errors">
|
||||
**Problem**: Line API authentication failures
|
||||
|
||||
**Solution**:
|
||||
- Verify Channel ID, Channel Secret, and Channel Token are correct
|
||||
- Check that the channel is published and not in development mode
|
||||
- Ensure the Messaging API is enabled for your channel
|
||||
- Regenerate Channel Token if necessary
|
||||
</Accordion>
|
||||
|
||||
## Line API Features
|
||||
|
||||
Line offers various features you can integrate:
|
||||
|
||||
- **Rich Messages**: Cards, carousels, quick replies
|
||||
- **Flex Messages**: Custom layouts
|
||||
- **LIFF (Line Frontend Framework)**: Web apps within Line
|
||||
- **Line Login**: User authentication
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful setup:
|
||||
|
||||
1. **Test message flow** between Line and Chatwoot
|
||||
2. **Configure agent assignments** for Line conversations
|
||||
3. **Set up automated responses** if needed
|
||||
4. **Explore rich message features** for enhanced user experience
|
||||
5. **Review webhook logs** for debugging
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
- **Check Logs**: Review both Chatwoot and Ngrok logs
|
||||
- **Line Developers Documentation**: [Official Line API Docs](https://developers.line.biz/en/docs/)
|
||||
- **Common Errors**: See [Common Errors](/contributing/project-setup/common-errors)
|
||||
- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
|
||||
|
||||
## Useful Resources
|
||||
|
||||
- **Line Messaging API Documentation**: [https://developers.line.biz/en/docs/messaging-api/](https://developers.line.biz/en/docs/messaging-api/)
|
||||
- **Line Developer Console**: [https://developers.line.biz/console](https://developers.line.biz/console)
|
||||
- **Webhook Test Tool**: Available in Line Developer Console
|
||||
|
||||
---
|
||||
|
||||
Your Line integration is now ready for development and testing! 💬
|
||||
@@ -0,0 +1,314 @@
|
||||
---
|
||||
title: macOS Development Setup
|
||||
description: Complete guide to setting up your macOS development environment for Chatwoot contribution.
|
||||
sidebarTitle: macOS Setup
|
||||
---
|
||||
|
||||
# macOS Development Setup
|
||||
|
||||
This guide will help you set up your macOS development environment for contributing to Chatwoot. Open Terminal app and run the following commands.
|
||||
|
||||
## Installing the Standalone Command Line Tools
|
||||
|
||||
Open Terminal app and run:
|
||||
|
||||
```bash
|
||||
xcode-select --install
|
||||
```
|
||||
|
||||
This installs essential development tools including Git, GCC, and other command line utilities.
|
||||
|
||||
## Install Homebrew
|
||||
|
||||
Homebrew is the missing package manager for macOS:
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
|
||||
```
|
||||
|
||||
After installation, add Homebrew to your PATH (if not automatically added):
|
||||
|
||||
```bash
|
||||
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
|
||||
eval "$(/opt/homebrew/bin/brew shellenv)"
|
||||
```
|
||||
|
||||
## Install Git
|
||||
|
||||
```bash
|
||||
brew update
|
||||
brew install git
|
||||
```
|
||||
|
||||
Configure Git with your information:
|
||||
|
||||
```bash
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "your.email@example.com"
|
||||
```
|
||||
|
||||
## Install Ruby Version Manager
|
||||
|
||||
Choose between RVM or rbenv for managing Ruby versions.
|
||||
|
||||
### Option 1: Install RVM (Recommended)
|
||||
|
||||
```bash
|
||||
curl -L https://get.rvm.io | bash -s stable
|
||||
source ~/.rvm/scripts/rvm
|
||||
```
|
||||
|
||||
### Option 2: Install rbenv (Alternative)
|
||||
|
||||
```bash
|
||||
brew install rbenv ruby-build
|
||||
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
## Install Ruby
|
||||
|
||||
Chatwoot APIs are built on Ruby on Rails. You need to install Ruby 3.2.2.
|
||||
|
||||
### If using RVM:
|
||||
|
||||
```bash
|
||||
rvm install ruby-3.2.2
|
||||
rvm use 3.2.2 --default
|
||||
source ~/.rvm/scripts/rvm
|
||||
```
|
||||
|
||||
### If using rbenv:
|
||||
|
||||
```bash
|
||||
rbenv install 3.2.2
|
||||
rbenv global 3.2.2
|
||||
```
|
||||
|
||||
<Info>
|
||||
rbenv identifies the ruby version from `.ruby-version` file on the root of the project and loads it automatically.
|
||||
</Info>
|
||||
|
||||
Verify Ruby installation:
|
||||
|
||||
```bash
|
||||
ruby --version
|
||||
# Should output: ruby 3.2.2
|
||||
```
|
||||
|
||||
## Install Node.js
|
||||
|
||||
Chatwoot requires Node.js version 20:
|
||||
|
||||
```bash
|
||||
brew install node@20
|
||||
```
|
||||
|
||||
If you need to link Node.js 20:
|
||||
|
||||
```bash
|
||||
brew link node@20
|
||||
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
Verify Node.js installation:
|
||||
|
||||
```bash
|
||||
node --version
|
||||
# Should output: v20.x.x
|
||||
```
|
||||
|
||||
## Install pnpm
|
||||
|
||||
We use `pnpm` as our package manager for better performance:
|
||||
|
||||
```bash
|
||||
brew install pnpm
|
||||
```
|
||||
|
||||
Verify pnpm installation:
|
||||
|
||||
```bash
|
||||
pnpm --version
|
||||
```
|
||||
|
||||
## Install PostgreSQL
|
||||
|
||||
The database used in Chatwoot is PostgreSQL.
|
||||
|
||||
### Option 1: PostgresApp (Recommended)
|
||||
|
||||
1. Download and install PostgresApp from [https://postgresapp.com](https://postgresapp.com)
|
||||
2. This is the easiest way to get started with PostgreSQL on macOS
|
||||
3. Follow the setup instructions on their website
|
||||
|
||||
### Option 2: Homebrew Installation
|
||||
|
||||
```bash
|
||||
brew install postgresql@14
|
||||
```
|
||||
|
||||
Start PostgreSQL service:
|
||||
|
||||
```bash
|
||||
brew services start postgresql@14
|
||||
```
|
||||
|
||||
Create a PostgreSQL user:
|
||||
|
||||
```bash
|
||||
createuser -s postgres
|
||||
```
|
||||
|
||||
Connect to PostgreSQL to verify installation:
|
||||
|
||||
```bash
|
||||
psql postgres
|
||||
# Type \q to exit
|
||||
```
|
||||
|
||||
## Install Redis Server
|
||||
|
||||
Chatwoot uses Redis server for agent assignments and reporting:
|
||||
|
||||
```bash
|
||||
brew install redis
|
||||
```
|
||||
|
||||
Start the Redis service:
|
||||
|
||||
```bash
|
||||
brew services start redis
|
||||
```
|
||||
|
||||
Verify Redis installation:
|
||||
|
||||
```bash
|
||||
redis-cli ping
|
||||
# Should output: PONG
|
||||
```
|
||||
|
||||
## Install ImageMagick
|
||||
|
||||
Chatwoot uses ImageMagick library to resize images for previews and thumbnails:
|
||||
|
||||
```bash
|
||||
brew install imagemagick
|
||||
```
|
||||
|
||||
Verify ImageMagick installation:
|
||||
|
||||
```bash
|
||||
convert --version
|
||||
```
|
||||
|
||||
## Install Additional Dependencies
|
||||
|
||||
Install other useful development tools:
|
||||
|
||||
```bash
|
||||
# Install Yarn (alternative to pnpm if needed)
|
||||
brew install yarn
|
||||
|
||||
# Install SQLite (for testing)
|
||||
brew install sqlite
|
||||
|
||||
# Install libvips (for image processing)
|
||||
brew install libvips
|
||||
```
|
||||
|
||||
## Install Docker (Optional)
|
||||
|
||||
For development and testing with containers:
|
||||
|
||||
```bash
|
||||
# Install Docker Desktop
|
||||
brew install --cask docker
|
||||
```
|
||||
|
||||
Or download Docker Desktop from [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/).
|
||||
|
||||
## Environment Verification
|
||||
|
||||
Verify all installations are working:
|
||||
|
||||
```bash
|
||||
# Check versions
|
||||
ruby --version # Should be 3.2.2
|
||||
node --version # Should be v20.x.x
|
||||
pnpm --version # Should show pnpm version
|
||||
psql --version # Should show PostgreSQL version
|
||||
redis-cli --version # Should show Redis version
|
||||
convert --version # Should show ImageMagick version
|
||||
git --version # Should show Git version
|
||||
```
|
||||
|
||||
## Configure Shell Environment
|
||||
|
||||
Add useful aliases to your shell configuration file (`~/.zshrc` for Zsh):
|
||||
|
||||
```bash
|
||||
# Add to ~/.zshrc
|
||||
echo '# Chatwoot Development Aliases' >> ~/.zshrc
|
||||
echo 'alias cw-server="bundle exec rails server"' >> ~/.zshrc
|
||||
echo 'alias cw-console="bundle exec rails console"' >> ~/.zshrc
|
||||
echo 'alias cw-test="bundle exec rspec"' >> ~/.zshrc
|
||||
echo 'alias cw-migrate="bundle exec rails db:migrate"' >> ~/.zshrc
|
||||
|
||||
# Reload shell configuration
|
||||
source ~/.zshrc
|
||||
```
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
<Accordion title="Command line tools installation fails">
|
||||
**Solution**: Update macOS to the latest version and try again. You can also download Xcode from the App Store.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Homebrew installation permission errors">
|
||||
**Solution**:
|
||||
```bash
|
||||
sudo chown -R $(whoami) /opt/homebrew
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ruby installation fails with RVM">
|
||||
**Solution**:
|
||||
```bash
|
||||
# Install missing dependencies
|
||||
brew install openssl readline libyaml
|
||||
rvm reinstall 3.2.2 --with-openssl-dir=$(brew --prefix openssl)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="PostgreSQL connection refused">
|
||||
**Solution**:
|
||||
```bash
|
||||
# Restart PostgreSQL
|
||||
brew services restart postgresql@14
|
||||
|
||||
# Check if it's running
|
||||
brew services list | grep postgresql
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="ImageMagick installation issues">
|
||||
**Solution**:
|
||||
```bash
|
||||
# If you encounter issues, try:
|
||||
brew uninstall imagemagick
|
||||
brew install imagemagick
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
|
||||
- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
|
||||
- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)
|
||||
|
||||
---
|
||||
|
||||
Your macOS development environment is now ready for Chatwoot development! 🚀
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
title: Make Commands Setup
|
||||
description: Speed up your local development workflow with Make commands for Chatwoot.
|
||||
sidebarTitle: Make Setup
|
||||
---
|
||||
|
||||
# Speed up your local development with Make
|
||||
|
||||
Speed up your local development workflow with make commands for Chatwoot.
|
||||
|
||||
## Clone the repo and cd to the Chatwoot directory
|
||||
|
||||
Clone the repository and navigate to the Chatwoot directory:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/chatwoot/chatwoot.git
|
||||
cd chatwoot
|
||||
```
|
||||
|
||||
## Install Ruby & JavaScript dependencies
|
||||
|
||||
Install Ruby and JavaScript dependencies using the following command. This command runs Bundler and pnpm:
|
||||
|
||||
```bash
|
||||
make burn
|
||||
```
|
||||
|
||||
## Run database migrations
|
||||
|
||||
Apply necessary database schema changes to your development environment by running the following command:
|
||||
|
||||
```bash
|
||||
make db
|
||||
```
|
||||
|
||||
## Run database seed
|
||||
|
||||
Load some seed data to your development environment for testing by running the following command:
|
||||
|
||||
```bash
|
||||
make db_seed
|
||||
```
|
||||
|
||||
## Run dev server using Overmind
|
||||
|
||||
Start the development server using Overmind, a process manager that can run multiple processes concurrently:
|
||||
|
||||
```bash
|
||||
make run
|
||||
```
|
||||
|
||||
## Force run if ./.overmind.sock file exists
|
||||
|
||||
If the `make run` command fails due to the existence of a `./.overmind.sock` file, you can try using the following command:
|
||||
|
||||
```bash
|
||||
make force_run
|
||||
```
|
||||
|
||||
## Debug - Attach to backend via Overmind tmux session
|
||||
|
||||
For debugging purposes, you can attach to the backend via the Overmind tmux session using the following command:
|
||||
|
||||
```bash
|
||||
make debug
|
||||
```
|
||||
|
||||
## Debug worker
|
||||
|
||||
To debug the worker, use the following command:
|
||||
|
||||
```bash
|
||||
make debug_worker
|
||||
```
|
||||
|
||||
## Get Rails console
|
||||
|
||||
Access the Rails console, which provides an interactive environment for interacting with the Chatwoot application:
|
||||
|
||||
```bash
|
||||
make console
|
||||
```
|
||||
|
||||
## Build Docker image
|
||||
|
||||
Build the Docker image for the Chatwoot project:
|
||||
|
||||
```bash
|
||||
make docker
|
||||
```
|
||||
|
||||
## Workflow after pulling in the latest changes from `develop`
|
||||
|
||||
To update your development environment after pulling the latest changes from the `develop` branch, follow these steps:
|
||||
|
||||
```bash
|
||||
make burn # Install dependencies
|
||||
|
||||
make db # Run migrations
|
||||
|
||||
make run # Start the server
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues with Make commands:
|
||||
|
||||
- **Makefile Documentation**: Check the project's `Makefile` for available commands
|
||||
- **Overmind Documentation**: [https://github.com/DarthSim/overmind](https://github.com/DarthSim/overmind)
|
||||
- **Chatwoot Issues**: [GitHub Issues](https://github.com/chatwoot/chatwoot/issues)
|
||||
- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
|
||||
|
||||
---
|
||||
|
||||
Your Make-based development workflow is now ready for efficient Chatwoot development! 🚀
|
||||
@@ -0,0 +1,242 @@
|
||||
---
|
||||
title: Mobile App Development Setup
|
||||
description: Setup guide for Chatwoot mobile app development
|
||||
sidebarTitle: Mobile App Setup
|
||||
---
|
||||
|
||||
# Setup guide for mobile app
|
||||
|
||||
Complete guide to setting up the Chatwoot mobile app for development and contribution.
|
||||
|
||||
## Installation and setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before starting, ensure you have the following installed:
|
||||
|
||||
- [Node.js](https://nodejs.org/en/download/) (Latest LTS version)
|
||||
- [React Native CLI](https://reactnative.dev/docs/environment-setup)
|
||||
- [Expo CLI](https://docs.expo.dev/get-started/installation/)
|
||||
- [Expo Account](https://expo.dev/signup)
|
||||
|
||||
<Note>
|
||||
To learn more about the most up-to-date instructions, please refer to the guide available [here](https://docs.expo.dev/get-started/set-up-your-environment/).
|
||||
</Note>
|
||||
|
||||
### Clone the repository
|
||||
|
||||
```bash
|
||||
git clone git@github.com:chatwoot/chatwoot-mobile-app.git
|
||||
cd chatwoot-mobile-app
|
||||
```
|
||||
|
||||
### Install dependencies
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### Install Expo CLI
|
||||
|
||||
```bash
|
||||
pnpm install -g expo-cli
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Create your environment configuration file:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Configure the following environment variables:
|
||||
|
||||
| Name | Description | Default Value | Required |
|
||||
| ---------------------------------------- | ------------------------------------------- | ------------------------ | -------- |
|
||||
| EXPO_PUBLIC_CHATWOOT_WEBSITE_TOKEN | Web widget token for in-app support | - | No |
|
||||
| EXPO_PUBLIC_CHATWOOT_BASE_URL | Self-hosted installation URL | https://app.chatwoot.com | Yes |
|
||||
| EXPO_PUBLIC_JUNE_SDK_KEY | June analytics SDK key | - | No |
|
||||
| EXPO_PUBLIC_MINIMUM_CHATWOOT_VERSION | Minimum supported Chatwoot version | - | Yes |
|
||||
| EXPO_PUBLIC_SENTRY_DSN | Sentry DSN URL for error reporting | - | No |
|
||||
| EXPO_PUBLIC_PROJECT_ID | Expo project identifier | - | Yes |
|
||||
| EXPO_PUBLIC_APP_SLUG | Application slug for Expo | - | Yes |
|
||||
| EXPO_PUBLIC_SENTRY_PROJECT_NAME | Project name in Sentry | - | No |
|
||||
| EXPO_PUBLIC_SENTRY_ORG_NAME | Organization name in Sentry | - | No |
|
||||
| EXPO_PUBLIC_IOS_GOOGLE_SERVICES_FILE | Path to iOS Google Services config file | - | No |
|
||||
| EXPO_PUBLIC_ANDROID_GOOGLE_SERVICES_FILE | Path to Android Google Services config file | - | No |
|
||||
| EXPO_APPLE_ID | Apple Developer account ID | - | No |
|
||||
| EXPO_APPLE_TEAM_ID | Apple Developer team ID | - | No |
|
||||
| EXPO_STORYBOOK_ENABLED | Enable/disable Storybook | false | No |
|
||||
|
||||
## Generate the native code
|
||||
|
||||
```bash
|
||||
pnpm generate
|
||||
```
|
||||
|
||||
This command generates native Android and iOS directories using [Prebuild](https://docs.expo.dev/workflow/continuous-native-generation/).
|
||||
|
||||
<Warning>
|
||||
You need to run pre-build if you add a new native dependency to your project or change the project configuration in Expo app config (app.config.ts).
|
||||
</Warning>
|
||||
|
||||
## How to run the app
|
||||
|
||||
Connect your iPhone/Android device and run the following command to install the app on your device.
|
||||
|
||||
### iOS Development
|
||||
|
||||
```bash
|
||||
pnpm run:ios
|
||||
```
|
||||
|
||||
### Android Development
|
||||
|
||||
```bash
|
||||
pnpm run:android
|
||||
```
|
||||
|
||||
## Package Installation
|
||||
|
||||
<Warning>
|
||||
Please always install packages using the command `npx expo install package-name` instead of `pnpm install package-name`.
|
||||
</Warning>
|
||||
|
||||
This is crucial for native dependencies because Expo will automatically install the correct compatible version, while pnpm/yarn/npm may install the latest version, which may not be compatible.
|
||||
|
||||
```bash
|
||||
# Correct way to install packages
|
||||
npx expo install package-name
|
||||
|
||||
# Incorrect way (may cause compatibility issues)
|
||||
pnpm install package-name
|
||||
```
|
||||
|
||||
## Push notification
|
||||
|
||||
If you are using the community edition of Chatwoot, you can now use the [official mobile app](https://www.chatwoot.com/mobile-apps) with push notifications without any additional configuration.
|
||||
|
||||
For more details, please refer to the [push notification documentation](https://www.chatwoot.com/hc/handbook/articles/1687935909-push-notification).
|
||||
|
||||
## Build & Submit using EAS
|
||||
|
||||
We use Expo Application Services (EAS) for building, deploying, and submitting the app to app stores. EAS Build and Submit is available to anyone with an Expo account, regardless of whether you pay for EAS or use our Free plan.
|
||||
|
||||
You can sign up at [Expo EAS](https://expo.dev/eas).
|
||||
|
||||
### Build the app
|
||||
|
||||
#### iOS Build
|
||||
|
||||
```bash
|
||||
pnpm run build:ios:local
|
||||
```
|
||||
|
||||
#### Android Build
|
||||
|
||||
```bash
|
||||
pnpm run build:android:local
|
||||
```
|
||||
|
||||
### Submit the app
|
||||
|
||||
#### iOS Submission
|
||||
|
||||
```bash
|
||||
pnpm submit:ios
|
||||
```
|
||||
|
||||
#### Android Submission
|
||||
|
||||
```bash
|
||||
pnpm submit:android
|
||||
```
|
||||
|
||||
When you run the above command, you will be prompted to provide a path to a local app binary file. Please select the file that you built in the previous step:
|
||||
|
||||
- **iOS**: `.ipa` file
|
||||
- **Android**: `.aab` file
|
||||
|
||||
<Note>
|
||||
It may take a while to complete the submission process. You will see the status of the submission on your terminal.
|
||||
</Note>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Accordion title="Metro bundler issues">
|
||||
**Problem**: Metro bundler fails to start or bundle
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Clear cache and restart
|
||||
pnpm clear
|
||||
pnpm start --reset-cache
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="iOS build fails">
|
||||
**Problem**: iOS build or simulator issues
|
||||
|
||||
**Solution**:
|
||||
- Ensure Xcode is properly installed
|
||||
- Check iOS simulator version compatibility
|
||||
- Clear derived data in Xcode
|
||||
- Restart Metro bundler
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Android build fails">
|
||||
**Problem**: Android build or emulator issues
|
||||
|
||||
**Solution**:
|
||||
- Verify Android Studio setup
|
||||
- Check SDK versions and build tools
|
||||
- Ensure emulator is running
|
||||
- Clear Gradle cache
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Expo CLI issues">
|
||||
**Problem**: Expo commands fail
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Update Expo CLI
|
||||
npm install -g @expo/cli@latest
|
||||
|
||||
# Login to Expo
|
||||
expo login
|
||||
|
||||
# Clear Expo cache
|
||||
expo r -c
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
## Contributing Guidelines
|
||||
|
||||
When contributing to the mobile app:
|
||||
|
||||
1. **Follow coding standards**: Use ESLint and Prettier configurations
|
||||
2. **Write tests**: Include unit tests for new features
|
||||
3. **Test on both platforms**: Ensure iOS and Android compatibility
|
||||
4. **Update documentation**: Document new features and changes
|
||||
5. **Check performance**: Monitor app performance impact
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
- **Expo Documentation**: [Official Expo Docs](https://docs.expo.dev/)
|
||||
- **React Native Documentation**: [React Native Docs](https://reactnative.dev/docs/getting-started)
|
||||
- **GitHub Issues**: [Mobile App Issues](https://github.com/chatwoot/chatwoot-mobile-app/issues)
|
||||
- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
|
||||
|
||||
## Useful Resources
|
||||
|
||||
- **Expo Development**: [https://docs.expo.dev/](https://docs.expo.dev/)
|
||||
- **React Native**: [https://reactnative.dev/](https://reactnative.dev/)
|
||||
- **EAS Build**: [https://docs.expo.dev/build/introduction/](https://docs.expo.dev/build/introduction/)
|
||||
- **EAS Submit**: [https://docs.expo.dev/submit/introduction/](https://docs.expo.dev/submit/introduction/)
|
||||
|
||||
---
|
||||
|
||||
Your Chatwoot mobile app development environment is now ready! 📱
|
||||
@@ -1,589 +1,181 @@
|
||||
---
|
||||
title: Project Setup Guide
|
||||
description: Complete guide to setting up Chatwoot for development and contribution
|
||||
description: Complete guide to setting up and running Chatwoot in development mode
|
||||
sidebarTitle: Setup Guide
|
||||
---
|
||||
|
||||
# Project Setup Guide
|
||||
# Project Setup
|
||||
|
||||
This comprehensive guide will walk you through setting up Chatwoot for development, from initial repository setup to running your first successful build.
|
||||
This guide will help you to setup and run Chatwoot in development mode. Please make sure you have completed the environment setup.
|
||||
|
||||
## Prerequisites Check
|
||||
|
||||
Before starting, ensure you have completed the [Local Development Setup](../environment-setup/local-development) guide and have all required dependencies installed.
|
||||
|
||||
### Quick Prerequisites Verification
|
||||
## Clone the repo
|
||||
|
||||
```bash
|
||||
# Check Ruby version (should be 3.3.3)
|
||||
ruby --version
|
||||
# change location to the path you want chatwoot to be installed
|
||||
cd ~
|
||||
|
||||
# Check Node.js version (should be 20+)
|
||||
node --version
|
||||
|
||||
# Check PostgreSQL
|
||||
psql --version
|
||||
|
||||
# Check Redis
|
||||
redis-cli --version
|
||||
|
||||
# Check Git
|
||||
git --version
|
||||
```
|
||||
|
||||
## Repository Setup
|
||||
|
||||
### 1. Fork and Clone
|
||||
|
||||
```bash
|
||||
# Fork the repository on GitHub first
|
||||
# Then clone your fork
|
||||
git clone https://github.com/YOUR_USERNAME/chatwoot.git
|
||||
# clone the repo and cd to chatwoot dir
|
||||
git clone https://github.com/chatwoot/chatwoot.git
|
||||
cd chatwoot
|
||||
|
||||
# Add upstream remote for syncing
|
||||
git remote add upstream https://github.com/chatwoot/chatwoot.git
|
||||
|
||||
# Verify remotes
|
||||
git remote -v
|
||||
# Should show:
|
||||
# origin https://github.com/YOUR_USERNAME/chatwoot.git (fetch)
|
||||
# origin https://github.com/YOUR_USERNAME/chatwoot.git (push)
|
||||
# upstream https://github.com/chatwoot/chatwoot.git (fetch)
|
||||
# upstream https://github.com/chatwoot/chatwoot.git (push)
|
||||
```
|
||||
|
||||
### 2. Branch Strategy
|
||||
## Install Ruby & Javascript dependencies
|
||||
|
||||
Use the following command to run `bundle && pnpm install` to install ruby and Javascript dependencies.
|
||||
|
||||
```bash
|
||||
# Create a development branch
|
||||
git checkout -b develop
|
||||
|
||||
# For feature work, create feature branches
|
||||
git checkout -b feature/your-feature-name
|
||||
|
||||
# Keep your fork synced
|
||||
git fetch upstream
|
||||
git checkout develop
|
||||
git merge upstream/develop
|
||||
git push origin develop
|
||||
make burn
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
This would install all required dependencies for Chatwoot application.
|
||||
|
||||
### 1. Environment File Setup
|
||||
<Warning>
|
||||
If you face issue with pg gem, please refer to [Common Errors](/contributing/project-setup/common-errors#pg-gem-installation-error)
|
||||
</Warning>
|
||||
|
||||
## Setup environment variables
|
||||
|
||||
```bash
|
||||
# Copy the example environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Open the file for editing
|
||||
nano .env
|
||||
```
|
||||
|
||||
### 2. Basic Configuration
|
||||
Please refer to [environment-variables](/contributing/project-setup/environment-variables) to read on setting environment variables.
|
||||
|
||||
Update your `.env` file with the following essential settings:
|
||||
## Setup rails server
|
||||
|
||||
```bash
|
||||
# Rails Environment
|
||||
RAILS_ENV=development
|
||||
NODE_ENV=development
|
||||
|
||||
# Application URLs
|
||||
FRONTEND_URL=http://localhost:3000
|
||||
FORCE_SSL=false
|
||||
|
||||
# Database Configuration
|
||||
DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
|
||||
# Email Configuration (for development)
|
||||
MAILER_SENDER_EMAIL=dev@chatwoot.local
|
||||
SMTP_ADDRESS=localhost
|
||||
SMTP_PORT=1025
|
||||
|
||||
# File Storage
|
||||
ACTIVE_STORAGE_SERVICE=local
|
||||
|
||||
# Development Features
|
||||
ENABLE_DEVELOPMENT_FEATURES=true
|
||||
LOG_LEVEL=debug
|
||||
RAILS_LOG_LEVEL=debug
|
||||
|
||||
# Disable SSL in development
|
||||
SMTP_ENABLE_STARTTLS_AUTO=false
|
||||
SMTP_TLS=false
|
||||
```
|
||||
|
||||
### 3. Generate Secret Keys
|
||||
|
||||
```bash
|
||||
# Generate secret key base
|
||||
bundle exec rails secret
|
||||
|
||||
# Add to your .env file
|
||||
echo "SECRET_KEY_BASE=your-generated-secret" >> .env
|
||||
```
|
||||
|
||||
## Database Setup
|
||||
|
||||
### 1. Database Creation
|
||||
|
||||
```bash
|
||||
# Create development and test databases
|
||||
bundle exec rails db:create
|
||||
|
||||
# Expected output:
|
||||
# Created database 'chatwoot_development'
|
||||
# Created database 'chatwoot_test'
|
||||
```
|
||||
|
||||
### 2. Database Migration
|
||||
|
||||
```bash
|
||||
# Run database migrations
|
||||
bundle exec rails db:migrate
|
||||
|
||||
# Check migration status
|
||||
bundle exec rails db:migrate:status
|
||||
```
|
||||
|
||||
### 3. Database Seeding
|
||||
|
||||
```bash
|
||||
# Seed the database with sample data
|
||||
bundle exec rails db:seed
|
||||
|
||||
# This creates:
|
||||
# - Sample account
|
||||
# - Admin user
|
||||
# - Sample conversations
|
||||
# - Test data for development
|
||||
```
|
||||
|
||||
### 4. Test Database Setup
|
||||
|
||||
```bash
|
||||
# Prepare test database
|
||||
RAILS_ENV=test bundle exec rails db:create
|
||||
RAILS_ENV=test bundle exec rails db:migrate
|
||||
```
|
||||
|
||||
## Dependency Installation
|
||||
|
||||
### 1. Ruby Dependencies
|
||||
|
||||
```bash
|
||||
# Install Ruby gems
|
||||
bundle install
|
||||
|
||||
# If you encounter issues, try:
|
||||
bundle install --retry=3
|
||||
|
||||
# For development and test gems
|
||||
bundle install --with development test
|
||||
```
|
||||
|
||||
### 2. Node.js Dependencies
|
||||
|
||||
```bash
|
||||
# Install Node.js packages
|
||||
pnpm install
|
||||
|
||||
# If pnpm is not available, install it first:
|
||||
npm install -g pnpm
|
||||
|
||||
# Clear cache if needed
|
||||
pnpm store prune
|
||||
```
|
||||
|
||||
### 3. Additional Tools
|
||||
|
||||
```bash
|
||||
# Install Foreman for process management
|
||||
gem install foreman
|
||||
|
||||
# Install MailHog for email testing (optional)
|
||||
# macOS
|
||||
brew install mailhog
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install mailhog
|
||||
|
||||
# Or download binary from GitHub releases
|
||||
```
|
||||
|
||||
## Application Startup
|
||||
|
||||
### 1. Using Foreman (Recommended)
|
||||
|
||||
```bash
|
||||
# Start all services with Foreman
|
||||
# run db migrations
|
||||
make db
|
||||
# fireup the server
|
||||
foreman start -f Procfile.dev
|
||||
|
||||
# This starts:
|
||||
# - Rails server (port 3000)
|
||||
# - Webpack dev server
|
||||
# - Sidekiq worker
|
||||
```
|
||||
|
||||
### 2. Manual Startup
|
||||
<Note>
|
||||
If you have overmind installed, use `make run` to run the server.
|
||||
</Note>
|
||||
|
||||
If you prefer to run services separately:
|
||||
## Login with credentials
|
||||
|
||||
```bash
|
||||
# Terminal 1: Rails server
|
||||
bundle exec rails server -p 3000
|
||||
|
||||
# Terminal 2: Webpack dev server
|
||||
pnpm run dev
|
||||
|
||||
# Terminal 3: Sidekiq worker
|
||||
bundle exec sidekiq
|
||||
|
||||
# Terminal 4: MailHog (optional)
|
||||
mailhog
|
||||
http://localhost:3000
|
||||
user name: john@acme.inc
|
||||
password: Password1!
|
||||
```
|
||||
|
||||
### 3. Verify Installation
|
||||
## Testing chat widget in your local environment
|
||||
|
||||
Once all services are running, verify your setup:
|
||||
|
||||
- **Web Application**: http://localhost:3000
|
||||
- **API Health Check**: http://localhost:3000/api
|
||||
- **Sidekiq Web UI**: http://localhost:3000/sidekiq
|
||||
- **MailHog**: http://localhost:8025 (if running)
|
||||
|
||||
## Initial Login
|
||||
|
||||
### Default Credentials
|
||||
|
||||
After seeding the database, you can log in with:
|
||||
When running Chatwoot in development environment, the chat widget can be accessed under the following URL.
|
||||
|
||||
```
|
||||
Email: john@acme.inc
|
||||
Password: Password1!
|
||||
http://localhost:3000/widget_tests
|
||||
```
|
||||
|
||||
### Creating Additional Users
|
||||
You can also test the `setUser` method by using
|
||||
|
||||
```
|
||||
http://localhost:3000/widget_tests?setUser=true
|
||||
```
|
||||
|
||||
## Docker for development
|
||||
|
||||
<Note>
|
||||
Follow this section only if you are trying to setup Chatwoot via docker. Else skip this.
|
||||
</Note>
|
||||
|
||||
The first time you start your development environment run the following two commands:
|
||||
|
||||
```bash
|
||||
# Access Rails console
|
||||
bundle exec rails console
|
||||
# build base image first
|
||||
docker compose build base
|
||||
|
||||
# Create a new user
|
||||
user = User.create!(
|
||||
name: "Your Name",
|
||||
email: "your.email@example.com",
|
||||
password: "Password123!",
|
||||
password_confirmation: "Password123!"
|
||||
)
|
||||
# build the server and worker
|
||||
docker compose build
|
||||
|
||||
# Make user an administrator
|
||||
user.account_users.first.update!(role: 'administrator')
|
||||
# prepare the database
|
||||
docker compose exec rails bundle exec rails db:chatwoot_prepare
|
||||
|
||||
# docker compose up
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### 1. Code Quality Setup
|
||||
Then browse http://localhost:3000
|
||||
|
||||
```bash
|
||||
# Install pre-commit hooks (optional but recommended)
|
||||
# Create .git/hooks/pre-commit
|
||||
cat > .git/hooks/pre-commit << 'EOF'
|
||||
#!/bin/sh
|
||||
# Run RuboCop
|
||||
bundle exec rubocop --parallel
|
||||
|
||||
# Run ESLint
|
||||
pnpm run lint
|
||||
|
||||
# Run tests
|
||||
bundle exec rspec --fail-fast
|
||||
EOF
|
||||
|
||||
chmod +x .git/hooks/pre-commit
|
||||
# To stop your environment use Control+C (on Mac) CTRL+C (on Win) or
|
||||
docker compose down
|
||||
# start the services
|
||||
docker compose up
|
||||
```
|
||||
|
||||
### 2. Running Tests
|
||||
When you change the service's Dockerfile or the contents of the build directory, run stop then build. (For example after modifying package.json or Gemfile)
|
||||
|
||||
```bash
|
||||
# Run Ruby tests
|
||||
bundle exec rspec
|
||||
|
||||
# Run specific test file
|
||||
bundle exec rspec spec/models/user_spec.rb
|
||||
|
||||
# Run JavaScript tests
|
||||
pnpm run test
|
||||
|
||||
# Run E2E tests (requires Playwright)
|
||||
pnpm exec playwright install
|
||||
pnpm run test:e2e
|
||||
|
||||
# Run tests with coverage
|
||||
COVERAGE=true bundle exec rspec
|
||||
docker compose stop
|
||||
docker compose build
|
||||
```
|
||||
|
||||
### 3. Code Linting and Formatting
|
||||
The docker-compose environment consists of:
|
||||
- chatwoot server
|
||||
- postgres
|
||||
- redis
|
||||
- webpacker-dev-server
|
||||
|
||||
If in case you encounter a seeding issue or you want reset the database you can do it using the following command:
|
||||
|
||||
```bash
|
||||
# Ruby linting with RuboCop
|
||||
bundle exec rubocop
|
||||
|
||||
# Auto-fix Ruby issues
|
||||
bundle exec rubocop -a
|
||||
|
||||
# JavaScript linting
|
||||
pnpm run lint
|
||||
|
||||
# Auto-fix JavaScript issues
|
||||
pnpm run lint:fix
|
||||
|
||||
# Format code with Prettier
|
||||
pnpm run format
|
||||
docker compose run --rm rails bundle exec rake db:reset
|
||||
```
|
||||
|
||||
## IDE Configuration
|
||||
This command essentially runs postgres and redis containers and then run the rake command inside the chatwoot server container.
|
||||
|
||||
### VS Code Setup
|
||||
## Running Cypress Tests
|
||||
|
||||
Create `.vscode/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"ruby.intellisense": "rubyLocate",
|
||||
"ruby.codeCompletion": "rcodetools",
|
||||
"ruby.format": "rubocop",
|
||||
"editor.formatOnSave": true,
|
||||
"editor.rulers": [120],
|
||||
"files.trimTrailingWhitespace": true,
|
||||
"files.insertFinalNewline": true,
|
||||
"eslint.autoFixOnSave": true,
|
||||
"prettier.requireConfig": true,
|
||||
"ruby.rubocop.executePath": "./bin/",
|
||||
"ruby.rubocop.onSave": true
|
||||
}
|
||||
```
|
||||
|
||||
Create `.vscode/extensions.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"recommendations": [
|
||||
"rebornix.ruby",
|
||||
"wingrunr21.vscode-ruby",
|
||||
"bradlc.vscode-tailwindcss",
|
||||
"esbenp.prettier-vscode",
|
||||
"dbaeumer.vscode-eslint",
|
||||
"ms-vscode.vscode-typescript-next",
|
||||
"shopify.ruby-lsp"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### RubyMine Setup
|
||||
|
||||
1. **Open Project**: File → Open → Select chatwoot directory
|
||||
2. **Configure Ruby SDK**: File → Project Structure → SDKs → Add Ruby SDK
|
||||
3. **Database Connection**: Database tool window → Add PostgreSQL connection
|
||||
4. **Code Style**: File → Settings → Editor → Code Style → Import scheme
|
||||
|
||||
## Debugging Setup
|
||||
|
||||
### Rails Debugging
|
||||
|
||||
Add to your code for debugging:
|
||||
|
||||
```ruby
|
||||
# Using Pry (recommended)
|
||||
binding.pry
|
||||
|
||||
# Using built-in debugger
|
||||
debugger
|
||||
|
||||
# Using byebug
|
||||
byebug
|
||||
```
|
||||
|
||||
### JavaScript Debugging
|
||||
|
||||
```javascript
|
||||
// Browser debugging
|
||||
console.log('Debug info:', variable);
|
||||
debugger;
|
||||
|
||||
// Node.js debugging
|
||||
console.log('Debug info:', variable);
|
||||
```
|
||||
|
||||
### Database Debugging
|
||||
Refer the docs to learn how to write cypress specs:
|
||||
- https://github.com/shakacode/cypress-on-rails
|
||||
- https://docs.cypress.io/guides/overview/why-cypress.html
|
||||
|
||||
```bash
|
||||
# Rails console
|
||||
bundle exec rails console
|
||||
|
||||
# Database console
|
||||
bundle exec rails dbconsole
|
||||
|
||||
# Check queries in development log
|
||||
tail -f log/development.log | grep -E "(SELECT|INSERT|UPDATE|DELETE)"
|
||||
# in terminal tab1
|
||||
overmind start -f Procfile.test
|
||||
# in terminal tab2
|
||||
pnpm cypress open --project ./test
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
## Debugging Docker for production
|
||||
|
||||
### Development Performance
|
||||
You can use our official Docker image from [https://hub.docker.com/r/chatwoot/chatwoot](https://hub.docker.com/r/chatwoot/chatwoot)
|
||||
|
||||
```bash
|
||||
# Use Spring for faster Rails commands
|
||||
bundle exec spring binstub --all
|
||||
|
||||
# Precompile assets for faster loading
|
||||
bundle exec rails assets:precompile
|
||||
|
||||
# Use parallel testing
|
||||
bundle exec rspec --parallel
|
||||
|
||||
# Monitor memory usage
|
||||
ps aux | grep -E "(ruby|node)" | head -10
|
||||
docker pull chatwoot/chatwoot
|
||||
```
|
||||
|
||||
### Database Performance
|
||||
|
||||
```ruby
|
||||
# Add to config/environments/development.rb for query analysis
|
||||
config.active_record.verbose_query_logs = true
|
||||
|
||||
# Enable query plan logging
|
||||
config.active_record.dump_schema_after_migration = false
|
||||
```
|
||||
|
||||
## Troubleshooting Setup Issues
|
||||
|
||||
### Common Setup Problems
|
||||
|
||||
<Accordion title="Bundle install fails">
|
||||
**Error**: `An error occurred while installing pg`
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# macOS
|
||||
brew install postgresql
|
||||
bundle config build.pg --with-pg-config=/usr/local/bin/pg_config
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install libpq-dev
|
||||
bundle install
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Database connection refused">
|
||||
**Error**: `could not connect to server: Connection refused`
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check if PostgreSQL is running
|
||||
sudo systemctl status postgresql
|
||||
|
||||
# Start PostgreSQL
|
||||
sudo systemctl start postgresql
|
||||
|
||||
# macOS with Homebrew
|
||||
brew services start postgresql
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Redis connection refused">
|
||||
**Error**: `Redis::CannotConnectError`
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check if Redis is running
|
||||
redis-cli ping
|
||||
|
||||
# Start Redis
|
||||
sudo systemctl start redis
|
||||
|
||||
# macOS with Homebrew
|
||||
brew services start redis
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Webpack compilation fails">
|
||||
**Error**: `Module not found` or compilation errors
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Clear webpack cache
|
||||
rm -rf tmp/cache/webpacker
|
||||
|
||||
# Reinstall node modules
|
||||
rm -rf node_modules
|
||||
pnpm install
|
||||
|
||||
# Restart webpack dev server
|
||||
pnpm run dev
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
### Verification Commands
|
||||
You can create an image yourselves by running the following command on the root directory.
|
||||
|
||||
```bash
|
||||
# Check all services are running
|
||||
ps aux | grep -E "(rails|sidekiq|webpack|mailhog)"
|
||||
|
||||
# Test database connection
|
||||
bundle exec rails runner "puts ActiveRecord::Base.connection.execute('SELECT 1').first"
|
||||
|
||||
# Test Redis connection
|
||||
bundle exec rails runner "puts Redis.new.ping"
|
||||
|
||||
# Check application health
|
||||
curl http://localhost:3000/api
|
||||
docker compose -f docker-compose.production.yaml build
|
||||
```
|
||||
|
||||
This will build the image which you can deploy in Kubernetes (GCP, Openshift, AWS, Azure or anywhere), Amazon ECS or Docker Swarm. You can tag this image and push this image to docker registry of your choice.
|
||||
|
||||
Remember to make the required environment variables available during the deployment.
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful setup:
|
||||
After completing this setup:
|
||||
|
||||
1. **Explore the Codebase**: Familiarize yourself with the project structure
|
||||
2. **Read Contributing Guidelines**: Review code standards and workflow
|
||||
3. **Pick Your First Issue**: Look for "good first issue" labels
|
||||
4. **Join the Community**: Connect with other contributors
|
||||
|
||||
### Useful Development Commands
|
||||
|
||||
```bash
|
||||
# Generate new migration
|
||||
bundle exec rails generate migration AddColumnToTable column:type
|
||||
|
||||
# Generate new model
|
||||
bundle exec rails generate model ModelName attribute:type
|
||||
|
||||
# Generate new controller
|
||||
bundle exec rails generate controller ControllerName
|
||||
|
||||
# Run specific migration
|
||||
bundle exec rails db:migrate:up VERSION=20231201000000
|
||||
|
||||
# Rollback migration
|
||||
bundle exec rails db:rollback STEP=1
|
||||
|
||||
# Reset database (careful!)
|
||||
bundle exec rails db:drop db:create db:migrate db:seed
|
||||
```
|
||||
1. **Verify Installation**: Access http://localhost:3000 and log in with the provided credentials
|
||||
2. **Explore the Code**: Start making changes and see them reflected in your development environment
|
||||
3. **Run Tests**: Execute the test suite to ensure everything works correctly
|
||||
4. **Check Troubleshooting**: If you encounter issues, refer to [Common Errors](/contributing/project-setup/common-errors)
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues during setup:
|
||||
|
||||
- **Check Common Errors**: See [Common Errors](./common-errors) guide
|
||||
- **Environment Variables**: Review [Environment Variables](./environment-variables) guide
|
||||
- **GitHub Issues**: Search existing issues or create a new one
|
||||
- **Discord Community**: Join the Chatwoot Discord server
|
||||
- **Documentation**: Check the official documentation
|
||||
- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
|
||||
- **Environment Variables**: See [Environment Variables](/contributing/project-setup/environment-variables)
|
||||
- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
|
||||
- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)
|
||||
|
||||
---
|
||||
|
||||
You're now ready to start developing with Chatwoot! Your development environment should be fully functional and ready for contribution.
|
||||
Your Chatwoot development environment is now ready for contribution! 🚀
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
title: Telegram App Integration Setup
|
||||
description: Setup Telegram app integration on your local machine for development
|
||||
sidebarTitle: Telegram Setup
|
||||
---
|
||||
|
||||
# Setup Telegram app integration on your local machine
|
||||
|
||||
Please follow the steps if you are trying to work with the Telegram integration on your local machine.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Telegram Bot Token from [BotFather](https://t.me/botfather)
|
||||
- Ngrok or similar tunneling service
|
||||
- Running Chatwoot development environment
|
||||
|
||||
## Setup Steps
|
||||
|
||||
### 1. Start Ngrok Server
|
||||
|
||||
Start a Ngrok server listening at port `3000` or the port you will be running the Chatwoot installation:
|
||||
|
||||
```bash
|
||||
# Install ngrok if you haven't already
|
||||
# Download from https://ngrok.com/download
|
||||
|
||||
# Start ngrok tunnel
|
||||
ngrok http 3000
|
||||
```
|
||||
|
||||
### 2. Update Environment Variables
|
||||
|
||||
Update the `.env` variable `FRONTEND_URL` in Chatwoot with the `https` version of the Ngrok URL:
|
||||
|
||||
```bash
|
||||
# In your .env file
|
||||
FRONTEND_URL=https://your-ngrok-subdomain.ngrok.io
|
||||
```
|
||||
|
||||
### 3. Start Chatwoot Server
|
||||
|
||||
Start the Chatwoot server and create a new Telegram channel with the token obtained from Telegram BotFather.
|
||||
|
||||
```bash
|
||||
# Start the development server
|
||||
make run
|
||||
# or
|
||||
foreman start -f Procfile.dev
|
||||
```
|
||||
|
||||
### 4. Create Telegram Channel
|
||||
|
||||
1. **Access Chatwoot**: Go to your Chatwoot instance (http://localhost:3000)
|
||||
2. **Navigate to Settings** → **Inboxes** → **Add Inbox**
|
||||
3. **Select Telegram** as the channel type
|
||||
4. **Enter Bot Token**: Paste the token you received from BotFather
|
||||
5. **Configure Channel**: Set up the channel name and other settings
|
||||
|
||||
## Verify Webhook Registration
|
||||
|
||||
While creating the channel, Chatwoot should have registered a webhook callback URL in Telegram for your Bot. You can verify whether this URL registration was done successfully by calling the Telegram API:
|
||||
|
||||
```bash
|
||||
GET https://api.telegram.org/bot{your_bot_token}/getWebhookInfo
|
||||
```
|
||||
|
||||
## Testing the Integration
|
||||
|
||||
If the webhook is registered correctly with Telegram, your Ngrok server should receive events for new Telegram messages, and new conversations will be created in Chatwoot.
|
||||
|
||||
### Test Steps
|
||||
|
||||
1. **Send a message** to your Telegram bot
|
||||
2. **Check Ngrok logs** to see if the webhook request is received
|
||||
3. **Check Chatwoot** to see if a new conversation is created
|
||||
4. **Reply from Chatwoot** to test bidirectional communication
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Accordion title="Webhook not registered">
|
||||
**Problem**: Telegram webhook registration fails
|
||||
|
||||
**Solution**:
|
||||
- Ensure your Ngrok URL is accessible publicly
|
||||
- Check that `FRONTEND_URL` is set correctly in your `.env` file
|
||||
- Verify the bot token is correct
|
||||
- Restart Chatwoot after updating environment variables
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Messages not appearing in Chatwoot">
|
||||
**Problem**: Telegram messages don't create conversations in Chatwoot
|
||||
|
||||
**Solution**:
|
||||
- Check Ngrok logs for incoming webhook requests
|
||||
- Verify the webhook URL in Telegram using the API call above
|
||||
- Check Chatwoot logs for any error messages
|
||||
- Ensure the channel is properly configured and enabled
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="SSL/TLS errors">
|
||||
**Problem**: SSL certificate issues with webhook
|
||||
|
||||
**Solution**:
|
||||
- Use the `https` version of your Ngrok URL
|
||||
- Ensure Ngrok is running properly
|
||||
- Try restarting Ngrok and updating the webhook
|
||||
</Accordion>
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful setup:
|
||||
|
||||
1. **Test message flow** between Telegram and Chatwoot
|
||||
2. **Configure agent assignments** for Telegram conversations
|
||||
3. **Set up automated responses** if needed
|
||||
4. **Review webhook logs** for debugging
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
- **Check Logs**: Review both Chatwoot and Ngrok logs
|
||||
- **Telegram Bot API**: [Official Documentation](https://core.telegram.org/bots/api)
|
||||
- **Common Errors**: See [Common Errors](/contributing/project-setup/common-errors)
|
||||
- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
|
||||
|
||||
---
|
||||
|
||||
Your Telegram integration is now ready for development and testing! 📱
|
||||
@@ -0,0 +1,246 @@
|
||||
---
|
||||
title: Ubuntu Development Setup
|
||||
description: Complete guide to setting up your Ubuntu development environment for Chatwoot contribution.
|
||||
sidebarTitle: Ubuntu Setup
|
||||
---
|
||||
|
||||
# Ubuntu Development Setup
|
||||
|
||||
This guide will help you set up your Ubuntu development environment for contributing to Chatwoot. These instructions work for Ubuntu 20.04, 22.04, and newer versions.
|
||||
|
||||
## Update System Packages
|
||||
|
||||
First, update your system packages to ensure you have the latest security updates:
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt upgrade -y
|
||||
```
|
||||
|
||||
## Install Essential Build Tools
|
||||
|
||||
Install fundamental development tools and dependencies:
|
||||
|
||||
```bash
|
||||
sudo apt install -y curl wget gnupg2 software-properties-common apt-transport-https ca-certificates build-essential libssl-dev libreadline-dev zlib1g-dev libyaml-dev libxml2-dev libxslt-dev
|
||||
```
|
||||
|
||||
## Install Git
|
||||
|
||||
Install Git for version control:
|
||||
|
||||
```bash
|
||||
sudo apt install -y git
|
||||
```
|
||||
|
||||
Configure Git with your information:
|
||||
|
||||
```bash
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "your.email@example.com"
|
||||
```
|
||||
|
||||
Verify Git installation:
|
||||
|
||||
```bash
|
||||
git --version
|
||||
```
|
||||
|
||||
## Install Ruby Version Manager (RVM)
|
||||
|
||||
Install RVM to manage Ruby versions:
|
||||
|
||||
```bash
|
||||
# Install GPG keys
|
||||
curl -sSL https://rvm.io/mpapis.asc | gpg --import -
|
||||
curl -sSL https://rvm.io/pkuczynski.asc | gpg --import -
|
||||
|
||||
# Install RVM
|
||||
curl -L https://get.rvm.io | bash -s stable
|
||||
|
||||
# Load RVM into current shell
|
||||
source ~/.rvm/scripts/rvm
|
||||
```
|
||||
|
||||
Add RVM to your shell profile:
|
||||
|
||||
```bash
|
||||
echo 'source ~/.rvm/scripts/rvm' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
## Install Ruby
|
||||
|
||||
Install Ruby 3.2.2 using RVM:
|
||||
|
||||
```bash
|
||||
# Install Ruby 3.2.2
|
||||
rvm install ruby-3.2.2
|
||||
|
||||
# Set as default Ruby version
|
||||
rvm use 3.2.2 --default
|
||||
|
||||
# Verify installation
|
||||
ruby --version
|
||||
# Should output: ruby 3.2.2
|
||||
```
|
||||
|
||||
## Install Node.js
|
||||
|
||||
Install Node.js 20 using NodeSource repository:
|
||||
|
||||
```bash
|
||||
# Add NodeSource repository
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
|
||||
# Install Node.js
|
||||
sudo apt install -y nodejs
|
||||
|
||||
# Verify installation
|
||||
node --version
|
||||
# Should output: v20.x.x
|
||||
|
||||
npm --version
|
||||
```
|
||||
|
||||
## Install pnpm
|
||||
|
||||
Install pnpm package manager:
|
||||
|
||||
```bash
|
||||
# Install pnpm globally
|
||||
npm install -g pnpm
|
||||
|
||||
# Verify installation
|
||||
pnpm --version
|
||||
```
|
||||
|
||||
## Install PostgreSQL
|
||||
|
||||
Install PostgreSQL database server:
|
||||
|
||||
```bash
|
||||
# Install PostgreSQL
|
||||
sudo apt install -y postgresql postgresql-contrib libpq-dev
|
||||
|
||||
# Start and enable PostgreSQL service
|
||||
sudo systemctl start postgresql
|
||||
sudo systemctl enable postgresql
|
||||
```
|
||||
|
||||
Configure PostgreSQL:
|
||||
|
||||
```bash
|
||||
# Switch to postgres user and create a superuser
|
||||
sudo -u postgres createuser --superuser $USER
|
||||
|
||||
# Set password for your user
|
||||
sudo -u postgres psql -c "ALTER USER $USER PASSWORD 'password';"
|
||||
|
||||
# Create a database for your user
|
||||
sudo -u postgres createdb $USER
|
||||
```
|
||||
|
||||
Verify PostgreSQL installation:
|
||||
|
||||
```bash
|
||||
psql --version
|
||||
psql -c "SELECT version();"
|
||||
```
|
||||
|
||||
## Install Redis
|
||||
|
||||
Install Redis server for background job processing:
|
||||
|
||||
```bash
|
||||
# Install Redis
|
||||
sudo apt install -y redis-server
|
||||
|
||||
# Start and enable Redis service
|
||||
sudo systemctl start redis-server
|
||||
sudo systemctl enable redis-server
|
||||
```
|
||||
|
||||
Verify Redis installation:
|
||||
|
||||
```bash
|
||||
redis-cli ping
|
||||
# Should output: PONG
|
||||
```
|
||||
|
||||
## Install ImageMagick
|
||||
|
||||
Install ImageMagick for image processing:
|
||||
|
||||
```bash
|
||||
sudo apt install -y imagemagick libmagickwand-dev
|
||||
```
|
||||
|
||||
Verify ImageMagick installation:
|
||||
|
||||
```bash
|
||||
convert --version
|
||||
```
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
<Accordion title="Ruby installation fails">
|
||||
**Solution**: Install missing dependencies:
|
||||
```bash
|
||||
sudo apt install -y autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev
|
||||
rvm reinstall 3.2.2
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="PostgreSQL authentication fails">
|
||||
**Solution**: Configure peer authentication:
|
||||
```bash
|
||||
sudo -u postgres psql
|
||||
ALTER USER postgres PASSWORD 'your_password';
|
||||
\q
|
||||
|
||||
# Edit pg_hba.conf
|
||||
sudo nano /etc/postgresql/*/main/pg_hba.conf
|
||||
# Change 'peer' to 'md5' for local connections
|
||||
sudo systemctl restart postgresql
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Permission denied for /usr/local">
|
||||
**Solution**: Fix ownership:
|
||||
```bash
|
||||
sudo chown -R $USER:$USER /usr/local
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Node.js installation issues">
|
||||
**Solution**: Use Node Version Manager (nvm):
|
||||
```bash
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
source ~/.bashrc
|
||||
nvm install 20
|
||||
nvm use 20
|
||||
nvm alias default 20
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="ImageMagick policy errors">
|
||||
**Solution**: Update ImageMagick policy:
|
||||
```bash
|
||||
sudo nano /etc/ImageMagick-6/policy.xml
|
||||
# Comment out or modify restrictive policies
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
|
||||
- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
|
||||
- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)
|
||||
- **Ubuntu Community**: [Ubuntu Forums](https://ubuntuforums.org/)
|
||||
|
||||
---
|
||||
|
||||
Your Ubuntu development environment is now ready for Chatwoot development! 🐧
|
||||
@@ -0,0 +1,320 @@
|
||||
---
|
||||
title: Windows Development Setup
|
||||
description: Complete guide to setting up your Windows development environment for Chatwoot contribution using WSL2.
|
||||
sidebarTitle: Windows Setup
|
||||
---
|
||||
|
||||
# Windows Development Setup
|
||||
|
||||
This guide will walk you through setting up your Windows development environment for contributing to Chatwoot. We'll use Windows Subsystem for Linux 2 (WSL2) which provides the best development experience on Windows.
|
||||
|
||||
## Requirements
|
||||
|
||||
You need to install the Windows Subsystem for Linux 2 (WSL2) on your Windows machine.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11
|
||||
- Administrator privileges on your Windows machine
|
||||
|
||||
## Step 1: Enable Developer Mode
|
||||
|
||||
The first step is to enable "Developer mode" in Windows. You can do this by opening up Settings and navigating to "Update & Security". In there, choose the tab on the left that reads "For Developers". Turn the "Developer mode" toggle on to enable it.
|
||||
|
||||
<img src="/contributing/project-setup/img/developer-mode.jpg" width="500" alt="Enable Developer Mode" />
|
||||
|
||||
## Step 2: Enable Windows Subsystem for Linux
|
||||
|
||||
Next you have to enable the Windows Subsystem for Linux. Open the "Control Panel" and go to "Programs and Features". Click on the link on the left "Turn Windows features on or off". Look for the "Windows Subsystem for Linux" option and select the checkbox next to it.
|
||||
|
||||
<img src="/contributing/project-setup/img/enable-wsl.jpg" width="500" alt="Enable WSL" />
|
||||
|
||||
You'll also need to enable "Virtual Machine Platform" for WSL2. Make sure both checkboxes are selected:
|
||||
- ✅ Windows Subsystem for Linux
|
||||
- ✅ Virtual Machine Platform
|
||||
|
||||
After enabling these features, restart your computer.
|
||||
|
||||
## Step 3: Install WSL2 and Ubuntu
|
||||
|
||||
### Option 1: Using Microsoft Store (Recommended)
|
||||
|
||||
1. **Open Microsoft Store** and search for "Ubuntu"
|
||||
2. **Install Ubuntu 22.04 LTS** (or latest LTS version)
|
||||
3. **Launch Ubuntu** from the Start Menu
|
||||
|
||||
### Option 2: Using Command Line
|
||||
|
||||
Open PowerShell as Administrator and run:
|
||||
|
||||
```powershell
|
||||
# Install WSL2 with Ubuntu
|
||||
wsl --install -d Ubuntu-22.04
|
||||
|
||||
# Set WSL2 as default version
|
||||
wsl --set-default-version 2
|
||||
```
|
||||
|
||||
## Step 4: Initial Ubuntu Setup
|
||||
|
||||
When you first launch Ubuntu, you'll be prompted to create a user account:
|
||||
|
||||
```bash
|
||||
# Create a username and password when prompted
|
||||
# This will be your Linux user account
|
||||
```
|
||||
|
||||
Update the system packages:
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
```
|
||||
|
||||
## Step 5: Install Core Dependencies
|
||||
|
||||
You need core Linux dependencies installed in order to install Ruby and other tools.
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y git-core curl zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev
|
||||
```
|
||||
|
||||
## Installing RVM & Ruby
|
||||
|
||||
Install additional dependencies required for RVM:
|
||||
|
||||
```bash
|
||||
sudo apt-get install -y libgdbm-dev libncurses5-dev automake libtool bison libffi-dev
|
||||
```
|
||||
|
||||
Install RVM & Ruby version 3.2.2:
|
||||
|
||||
```bash
|
||||
# Add RVM GPG keys
|
||||
gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
|
||||
|
||||
# Install RVM
|
||||
curl -sSL https://get.rvm.io | bash -s stable
|
||||
|
||||
# Load RVM into current session
|
||||
source ~/.rvm/scripts/rvm
|
||||
|
||||
# Install Ruby 3.2.2
|
||||
rvm install 3.2.2
|
||||
rvm use 3.2.2 --default
|
||||
|
||||
# Verify installation
|
||||
ruby -v
|
||||
```
|
||||
|
||||
## Install Node.js
|
||||
|
||||
Chatwoot requires Node.js version 20. Install Node.js from NodeSource using the following commands:
|
||||
|
||||
```bash
|
||||
curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
```
|
||||
|
||||
Verify Node.js installation:
|
||||
|
||||
```bash
|
||||
node --version
|
||||
# Should output: v20.x.x
|
||||
```
|
||||
|
||||
## Install pnpm
|
||||
|
||||
We use `pnpm` as the package manager for better performance:
|
||||
|
||||
```bash
|
||||
# Install pnpm globally
|
||||
npm install -g pnpm
|
||||
|
||||
# Verify installation
|
||||
pnpm --version
|
||||
```
|
||||
|
||||
## Install PostgreSQL
|
||||
|
||||
The database used in Chatwoot is PostgreSQL. Use the following commands to install PostgreSQL:
|
||||
|
||||
```bash
|
||||
sudo apt install -y postgresql postgresql-contrib
|
||||
```
|
||||
|
||||
The installation procedure created a user account called postgres that is associated with the default Postgres role. In order to use PostgreSQL, you can log into that account:
|
||||
|
||||
```bash
|
||||
sudo -u postgres psql
|
||||
```
|
||||
|
||||
Install `libpq-dev` dependencies for Ubuntu:
|
||||
|
||||
```bash
|
||||
sudo apt-get install -y libpq-dev
|
||||
```
|
||||
|
||||
Start PostgreSQL service:
|
||||
|
||||
```bash
|
||||
sudo service postgresql start
|
||||
```
|
||||
|
||||
Configure PostgreSQL to start automatically:
|
||||
|
||||
```bash
|
||||
echo 'sudo service postgresql start' >> ~/.bashrc
|
||||
```
|
||||
|
||||
Create a database user:
|
||||
|
||||
```bash
|
||||
# Switch to postgres user and create a superuser
|
||||
sudo -u postgres createuser --superuser $USER
|
||||
|
||||
# Set password for your user
|
||||
sudo -u postgres psql -c "ALTER USER $USER PASSWORD 'password';"
|
||||
```
|
||||
|
||||
## Install Redis Server
|
||||
|
||||
Chatwoot uses Redis server for agent assignments and reporting. To install `redis-server`:
|
||||
|
||||
```bash
|
||||
sudo apt-get install -y redis-server
|
||||
```
|
||||
|
||||
Start Redis service:
|
||||
|
||||
```bash
|
||||
sudo service redis-server start
|
||||
```
|
||||
|
||||
Configure Redis to start automatically:
|
||||
|
||||
```bash
|
||||
echo 'sudo service redis-server start' >> ~/.bashrc
|
||||
```
|
||||
|
||||
Enable Redis to start on system boot:
|
||||
|
||||
```bash
|
||||
sudo systemctl enable redis-server.service
|
||||
```
|
||||
|
||||
## Install ImageMagick
|
||||
|
||||
Chatwoot uses ImageMagick for image processing:
|
||||
|
||||
```bash
|
||||
sudo apt-get install -y imagemagick libmagickwand-dev
|
||||
```
|
||||
|
||||
## Configure Git
|
||||
|
||||
Set up Git with your information:
|
||||
|
||||
```bash
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "your.email@example.com"
|
||||
```
|
||||
|
||||
## Windows-Specific Configuration
|
||||
|
||||
### Install VS Code with WSL Extension
|
||||
|
||||
1. **Install Visual Studio Code** on Windows from [https://code.visualstudio.com/](https://code.visualstudio.com/)
|
||||
2. **Install Remote - WSL extension** from the Extensions marketplace
|
||||
3. **Open your project in WSL** by running `code .` from your WSL terminal
|
||||
|
||||
### Configure File Permissions
|
||||
|
||||
WSL2 may have file permission issues. Fix them:
|
||||
|
||||
```bash
|
||||
# Add to ~/.bashrc for better file permissions
|
||||
echo 'umask 022' >> ~/.bashrc
|
||||
|
||||
# Configure Git to ignore file mode changes
|
||||
git config --global core.filemode false
|
||||
```
|
||||
|
||||
## Environment Verification
|
||||
|
||||
Verify all installations are working correctly:
|
||||
|
||||
```bash
|
||||
# Check all versions
|
||||
ruby --version # Should be 3.2.2
|
||||
node --version # Should be v20.x.x
|
||||
pnpm --version # Should show pnpm version
|
||||
psql --version # Should show PostgreSQL version
|
||||
redis-cli ping # Should output: PONG
|
||||
convert --version # Should show ImageMagick version
|
||||
git --version # Should show Git version
|
||||
```
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
<Accordion title="WSL installation fails">
|
||||
**Solution**: Ensure virtualization is enabled in BIOS and Windows features are properly enabled:
|
||||
1. Restart computer and enter BIOS settings
|
||||
2. Enable Intel VT-x or AMD-V virtualization
|
||||
3. Enable Hyper-V in Windows Features
|
||||
4. Restart and try installation again
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ubuntu terminal won't open">
|
||||
**Solution**: Reset WSL or reinstall Ubuntu:
|
||||
```powershell
|
||||
# Reset Ubuntu (will delete all data)
|
||||
wsl --unregister Ubuntu-22.04
|
||||
wsl --install -d Ubuntu-22.04
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="PostgreSQL fails to start">
|
||||
**Solution**: Check if Windows PostgreSQL service is conflicting:
|
||||
```bash
|
||||
# Stop Windows PostgreSQL service first (run in Windows Command Prompt as Admin)
|
||||
net stop postgresql-x64-14
|
||||
|
||||
# Then start WSL2 PostgreSQL
|
||||
sudo service postgresql start
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Permission denied errors">
|
||||
**Solution**: Fix file permissions:
|
||||
```bash
|
||||
# For the entire project
|
||||
find . -type f -exec chmod 644 {} \;
|
||||
find . -type d -exec chmod 755 {} \;
|
||||
|
||||
# For executable files
|
||||
chmod +x bin/*
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Slow performance">
|
||||
**Solution**: Ensure code is stored in WSL2 filesystem:
|
||||
```bash
|
||||
# Good: Store code here (fast)
|
||||
/home/username/projects/chatwoot
|
||||
|
||||
# Avoid: Storing code here (slow)
|
||||
/mnt/c/Users/Username/projects/chatwoot
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
If you encounter issues during setup:
|
||||
|
||||
- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
|
||||
- **WSL2 Documentation**: [Microsoft WSL Documentation](https://docs.microsoft.com/en-us/windows/wsl/)
|
||||
- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
|
||||
- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)
|
||||
|
||||
---
|
||||
|
||||
Your Windows development environment with WSL2 is now ready for Chatwoot development! 🪟🐧
|
||||
Reference in New Issue
Block a user