add mintlify intro docs
This commit is contained in:
Tanmay Deep Sharma
@@ -0,0 +1,588 @@
|
||||
---
|
||||
title: Local Development Setup
|
||||
description: Set up Chatwoot for local development on your machine
|
||||
sidebarTitle: Local Development
|
||||
---
|
||||
|
||||
# Local Development Setup
|
||||
|
||||
This guide will help you set up Chatwoot for local development on your machine. Follow these steps to get a complete development environment running.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before setting up Chatwoot locally, ensure you have the following installed:
|
||||
|
||||
### Required Software
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Ruby" icon="gem">
|
||||
Ruby 3.3.3 (managed with rbenv or RVM)
|
||||
</Card>
|
||||
<Card title="Node.js" icon="node-js">
|
||||
Node.js 20+ with pnpm package manager
|
||||
</Card>
|
||||
<Card title="PostgreSQL" icon="database">
|
||||
PostgreSQL 13+ for the database
|
||||
</Card>
|
||||
<Card title="Redis" icon="redis">
|
||||
Redis 6+ for caching and background jobs
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### System Dependencies
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS">
|
||||
```bash
|
||||
# Install Homebrew if not already installed
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# Install dependencies
|
||||
brew install postgresql@15 redis imagemagick git
|
||||
|
||||
# Install rbenv for Ruby version management
|
||||
brew install rbenv ruby-build
|
||||
|
||||
# Install Node.js and pnpm
|
||||
brew install node
|
||||
npm install -g pnpm
|
||||
|
||||
# Start services
|
||||
brew services start postgresql@15
|
||||
brew services start redis
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Ubuntu/Debian">
|
||||
```bash
|
||||
# Update package list
|
||||
sudo apt update
|
||||
|
||||
# Install dependencies
|
||||
sudo apt install -y curl git build-essential libssl-dev libreadline-dev \
|
||||
zlib1g-dev libpq-dev imagemagick libmagickwand-dev libffi-dev \
|
||||
postgresql postgresql-contrib redis-server
|
||||
|
||||
# Install rbenv
|
||||
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
|
||||
|
||||
# Install Node.js (using NodeSource)
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
sudo apt install -y nodejs
|
||||
|
||||
# Install pnpm
|
||||
npm install -g pnpm
|
||||
|
||||
# Start services
|
||||
sudo systemctl start postgresql
|
||||
sudo systemctl start redis-server
|
||||
sudo systemctl enable postgresql
|
||||
sudo systemctl enable redis-server
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="CentOS/RHEL">
|
||||
```bash
|
||||
# Install EPEL repository
|
||||
sudo yum install -y epel-release
|
||||
|
||||
# Install dependencies
|
||||
sudo yum groupinstall -y "Development Tools"
|
||||
sudo yum install -y curl git openssl-devel readline-devel zlib-devel \
|
||||
postgresql-devel ImageMagick-devel libffi-devel postgresql-server \
|
||||
postgresql-contrib redis
|
||||
|
||||
# Initialize PostgreSQL
|
||||
sudo postgresql-setup initdb
|
||||
|
||||
# Install rbenv
|
||||
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
|
||||
|
||||
# Install Node.js
|
||||
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
|
||||
sudo yum install -y nodejs
|
||||
|
||||
# Install pnpm
|
||||
npm install -g pnpm
|
||||
|
||||
# Start services
|
||||
sudo systemctl start postgresql
|
||||
sudo systemctl start redis
|
||||
sudo systemctl enable postgresql
|
||||
sudo systemctl enable redis
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Ruby Setup
|
||||
|
||||
### Install Ruby with rbenv
|
||||
|
||||
```bash
|
||||
# Add rbenv to your shell profile
|
||||
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
|
||||
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
|
||||
# Install Ruby 3.3.3
|
||||
rbenv install 3.3.3
|
||||
rbenv global 3.3.3
|
||||
|
||||
# Verify installation
|
||||
ruby --version
|
||||
# Should output: ruby 3.3.3
|
||||
|
||||
# Install bundler
|
||||
gem install bundler
|
||||
```
|
||||
|
||||
### Alternative: Using RVM
|
||||
|
||||
```bash
|
||||
# Install RVM
|
||||
curl -sSL https://get.rvm.io | bash -s stable
|
||||
source ~/.rvm/scripts/rvm
|
||||
|
||||
# Install Ruby 3.3.3
|
||||
rvm install 3.3.3
|
||||
rvm use 3.3.3 --default
|
||||
|
||||
# Verify installation
|
||||
ruby --version
|
||||
gem install bundler
|
||||
```
|
||||
|
||||
## Database Setup
|
||||
|
||||
### PostgreSQL Configuration
|
||||
|
||||
```bash
|
||||
# Create PostgreSQL user (macOS with Homebrew)
|
||||
createuser -s chatwoot
|
||||
|
||||
# Create PostgreSQL user (Linux)
|
||||
sudo -u postgres createuser -s chatwoot
|
||||
|
||||
# Set password for the user
|
||||
sudo -u postgres psql
|
||||
postgres=# ALTER USER chatwoot PASSWORD 'password';
|
||||
postgres=# \q
|
||||
|
||||
# Create databases
|
||||
createdb chatwoot_development
|
||||
createdb chatwoot_test
|
||||
```
|
||||
|
||||
### PostgreSQL Authentication Setup
|
||||
|
||||
Edit PostgreSQL configuration to allow local connections:
|
||||
|
||||
```bash
|
||||
# Find pg_hba.conf location
|
||||
sudo -u postgres psql -c "SHOW hba_file;"
|
||||
|
||||
# Edit the file (example path)
|
||||
sudo nano /etc/postgresql/15/main/pg_hba.conf
|
||||
|
||||
# Add or modify these lines:
|
||||
local all chatwoot md5
|
||||
host all chatwoot 127.0.0.1/32 md5
|
||||
host all chatwoot ::1/128 md5
|
||||
|
||||
# Restart PostgreSQL
|
||||
sudo systemctl restart postgresql
|
||||
```
|
||||
|
||||
## Project Setup
|
||||
|
||||
### Clone the Repository
|
||||
|
||||
```bash
|
||||
# Fork the repository on GitHub first, then clone your fork
|
||||
git clone https://github.com/YOUR_USERNAME/chatwoot.git
|
||||
cd chatwoot
|
||||
|
||||
# Add upstream remote
|
||||
git remote add upstream https://github.com/chatwoot/chatwoot.git
|
||||
|
||||
# Verify remotes
|
||||
git remote -v
|
||||
```
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
```bash
|
||||
# Install Ruby dependencies
|
||||
bundle install
|
||||
|
||||
# Install Node.js dependencies
|
||||
pnpm install
|
||||
|
||||
# Install Playwright for E2E tests (optional)
|
||||
pnpm exec playwright install
|
||||
```
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
```bash
|
||||
# Copy environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Edit the environment file
|
||||
nano .env
|
||||
```
|
||||
|
||||
Update the `.env` file with your local configuration:
|
||||
|
||||
```bash
|
||||
# Database configuration
|
||||
DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
|
||||
# Application settings
|
||||
FRONTEND_URL=http://localhost:3000
|
||||
FORCE_SSL=false
|
||||
RAILS_ENV=development
|
||||
NODE_ENV=development
|
||||
|
||||
# Email configuration (for development)
|
||||
MAILER_SENDER_EMAIL=dev@chatwoot.local
|
||||
SMTP_ADDRESS=localhost
|
||||
SMTP_PORT=1025
|
||||
|
||||
# File storage (local)
|
||||
ACTIVE_STORAGE_SERVICE=local
|
||||
|
||||
# Development features
|
||||
ENABLE_DEVELOPMENT_FEATURES=true
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
### Database Initialization
|
||||
|
||||
```bash
|
||||
# Create and migrate the database
|
||||
bundle exec rails db:create
|
||||
bundle exec rails db:migrate
|
||||
|
||||
# Seed the database with sample data
|
||||
bundle exec rails db:seed
|
||||
|
||||
# Prepare the test database
|
||||
RAILS_ENV=test bundle exec rails db:create
|
||||
RAILS_ENV=test bundle exec rails db:migrate
|
||||
```
|
||||
|
||||
## Running the Application
|
||||
|
||||
### Start Development Servers
|
||||
|
||||
You'll need to run multiple processes for full development:
|
||||
|
||||
#### Option 1: Using Foreman (Recommended)
|
||||
|
||||
```bash
|
||||
# Install foreman
|
||||
gem install foreman
|
||||
|
||||
# Start all services
|
||||
foreman start -f Procfile.dev
|
||||
```
|
||||
|
||||
#### Option 2: Manual Process Management
|
||||
|
||||
Open multiple terminal windows/tabs:
|
||||
|
||||
```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 (for email testing)
|
||||
mailhog
|
||||
```
|
||||
|
||||
### Access the Application
|
||||
|
||||
Once all services are running:
|
||||
|
||||
- **Web Application**: http://localhost:3000
|
||||
- **API Documentation**: http://localhost:3000/swagger
|
||||
- **Sidekiq Web UI**: http://localhost:3000/sidekiq
|
||||
- **MailHog (Email)**: http://localhost:8025
|
||||
|
||||
### Default Login Credentials
|
||||
|
||||
After seeding the database, you can log in with:
|
||||
|
||||
- **Email**: john@acme.inc
|
||||
- **Password**: Password1!
|
||||
|
||||
## Development Tools
|
||||
|
||||
### Code Quality Tools
|
||||
|
||||
```bash
|
||||
# Install development gems
|
||||
bundle install --with development test
|
||||
|
||||
# Run RuboCop (Ruby linter)
|
||||
bundle exec rubocop
|
||||
|
||||
# Run RuboCop with auto-fix
|
||||
bundle exec rubocop -a
|
||||
|
||||
# Run ESLint (JavaScript linter)
|
||||
pnpm run lint
|
||||
|
||||
# Run ESLint with auto-fix
|
||||
pnpm run lint:fix
|
||||
|
||||
# Run Prettier (code formatter)
|
||||
pnpm run format
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```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
|
||||
pnpm run test:e2e
|
||||
|
||||
# Run tests with coverage
|
||||
COVERAGE=true bundle exec rspec
|
||||
```
|
||||
|
||||
### Database Operations
|
||||
|
||||
```bash
|
||||
# Reset database
|
||||
bundle exec rails db:drop db:create db:migrate db:seed
|
||||
|
||||
# Generate migration
|
||||
bundle exec rails generate migration AddColumnToTable column:type
|
||||
|
||||
# Run migrations
|
||||
bundle exec rails db:migrate
|
||||
|
||||
# Rollback migration
|
||||
bundle exec rails db:rollback
|
||||
|
||||
# Check migration status
|
||||
bundle exec rails db:migrate:status
|
||||
```
|
||||
|
||||
## IDE and Editor Setup
|
||||
|
||||
### VS Code Configuration
|
||||
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
### Recommended VS Code Extensions
|
||||
|
||||
```json
|
||||
{
|
||||
"recommendations": [
|
||||
"rebornix.ruby",
|
||||
"wingrunr21.vscode-ruby",
|
||||
"bradlc.vscode-tailwindcss",
|
||||
"esbenp.prettier-vscode",
|
||||
"dbaeumer.vscode-eslint",
|
||||
"ms-vscode.vscode-typescript-next",
|
||||
"bradlc.vscode-tailwindcss"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### RubyMine Configuration
|
||||
|
||||
1. Open the project in RubyMine
|
||||
2. Configure Ruby SDK: File → Project Structure → SDKs
|
||||
3. Set up database connection in Database tool window
|
||||
4. Configure code style: File → Settings → Editor → Code Style
|
||||
|
||||
## Debugging
|
||||
|
||||
### Rails Debugging
|
||||
|
||||
```ruby
|
||||
# Add to your code for debugging
|
||||
binding.pry
|
||||
|
||||
# Or use the built-in debugger
|
||||
debugger
|
||||
```
|
||||
|
||||
### JavaScript Debugging
|
||||
|
||||
```javascript
|
||||
// Add to your code
|
||||
console.log('Debug info:', variable);
|
||||
debugger;
|
||||
```
|
||||
|
||||
### Database Debugging
|
||||
|
||||
```bash
|
||||
# Rails console
|
||||
bundle exec rails console
|
||||
|
||||
# Database console
|
||||
bundle exec rails dbconsole
|
||||
|
||||
# Check database queries in logs
|
||||
tail -f log/development.log | grep SQL
|
||||
```
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Bundle Install Issues
|
||||
|
||||
<Accordion title="pg gem installation fails">
|
||||
```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="ImageMagick issues">
|
||||
```bash
|
||||
# macOS
|
||||
brew install imagemagick pkg-config
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install libmagickwand-dev
|
||||
|
||||
# Then reinstall the gem
|
||||
bundle pristine rmagick
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
### Node.js Issues
|
||||
|
||||
<Accordion title="pnpm install fails">
|
||||
```bash
|
||||
# Clear cache and reinstall
|
||||
pnpm store prune
|
||||
rm -rf node_modules
|
||||
pnpm install
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Webpack compilation errors">
|
||||
```bash
|
||||
# Clear webpack cache
|
||||
rm -rf tmp/cache/webpacker
|
||||
pnpm run dev
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
### Database Issues
|
||||
|
||||
<Accordion title="Database connection refused">
|
||||
```bash
|
||||
# Check if PostgreSQL is running
|
||||
sudo systemctl status postgresql
|
||||
|
||||
# Start PostgreSQL if not running
|
||||
sudo systemctl start postgresql
|
||||
|
||||
# Check connection
|
||||
psql -U chatwoot -d chatwoot_development -h localhost
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Permission denied for database">
|
||||
```bash
|
||||
# Reset PostgreSQL user password
|
||||
sudo -u postgres psql
|
||||
postgres=# ALTER USER chatwoot PASSWORD 'password';
|
||||
postgres=# \q
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Development Performance Tips
|
||||
|
||||
```bash
|
||||
# Use spring for faster Rails commands
|
||||
bundle exec spring binstub --all
|
||||
|
||||
# Use bootsnap for faster boot times (already included)
|
||||
# Ensure tmp/cache directory exists
|
||||
mkdir -p tmp/cache
|
||||
|
||||
# Use parallel testing
|
||||
bundle exec rspec --parallel
|
||||
|
||||
# Optimize database queries
|
||||
# Add to config/environments/development.rb
|
||||
config.active_record.verbose_query_logs = true
|
||||
```
|
||||
|
||||
### Memory Usage Optimization
|
||||
|
||||
```bash
|
||||
# Monitor memory usage
|
||||
ps aux | grep ruby
|
||||
ps aux | grep node
|
||||
|
||||
# Use jemalloc for better memory management
|
||||
export MALLOC_ARENA_MAX=2
|
||||
bundle exec rails server
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once you have your development environment set up:
|
||||
|
||||
1. **Read the Contributing Guidelines**: Check out the [contributing guide](../introduction) for code standards and workflow
|
||||
2. **Explore the Codebase**: Familiarize yourself with the project structure
|
||||
3. **Pick an Issue**: Look for "good first issue" labels on GitHub
|
||||
4. **Join the Community**: Connect with other contributors on Discord or GitHub Discussions
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues during setup:
|
||||
|
||||
- **GitHub Issues**: Search existing issues or create a new one
|
||||
- **Discord Community**: Join the Chatwoot Discord server
|
||||
- **Documentation**: Check the official documentation
|
||||
- **Stack Overflow**: Search for Chatwoot-related questions
|
||||
|
||||
---
|
||||
|
||||
You're now ready to start contributing to Chatwoot! The development environment should be fully functional and ready for coding.
|
||||
@@ -0,0 +1,322 @@
|
||||
---
|
||||
title: Contributing to Chatwoot
|
||||
description: Complete guide to contributing to Chatwoot - from setting up your development environment to submitting pull requests.
|
||||
sidebarTitle: Introduction
|
||||
---
|
||||
|
||||
Thank you for your interest in contributing to Chatwoot! This guide will help you get started with contributing to our open-source customer support platform. Whether you're fixing bugs, adding features, or improving documentation, your contributions are valuable to the community.
|
||||
|
||||
## Why Contribute to Chatwoot?
|
||||
|
||||
Contributing to Chatwoot offers many benefits:
|
||||
|
||||
- **Learn and Grow**: Work with modern technologies like Ruby on Rails, Vue.js, and PostgreSQL
|
||||
- **Make an Impact**: Help thousands of businesses improve their customer support
|
||||
- **Build Your Portfolio**: Showcase your contributions to a popular open-source project
|
||||
- **Join the Community**: Connect with developers and users from around the world
|
||||
- **Give Back**: Support the open-source ecosystem
|
||||
|
||||
## Ways to Contribute
|
||||
|
||||
There are many ways to contribute to Chatwoot:
|
||||
|
||||
### 🐛 Bug Reports and Fixes
|
||||
- Report bugs you encounter
|
||||
- Fix existing bugs in the codebase
|
||||
- Improve error handling and edge cases
|
||||
|
||||
### ✨ Feature Development
|
||||
- Implement new features
|
||||
- Enhance existing functionality
|
||||
- Improve user experience
|
||||
|
||||
### 📚 Documentation
|
||||
- Improve existing documentation
|
||||
- Write new guides and tutorials
|
||||
- Translate documentation to other languages
|
||||
|
||||
### 🧪 Testing
|
||||
- Write unit and integration tests
|
||||
- Perform manual testing
|
||||
- Improve test coverage
|
||||
|
||||
### 🎨 Design and UX
|
||||
- Improve user interface design
|
||||
- Enhance user experience
|
||||
- Create mockups and prototypes
|
||||
|
||||
### 🌍 Localization
|
||||
- Translate Chatwoot to new languages
|
||||
- Improve existing translations
|
||||
- Help with internationalization
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before you start contributing, make sure you have:
|
||||
|
||||
- **Git**: Version control system
|
||||
- **GitHub Account**: For submitting pull requests
|
||||
- **Development Environment**: See our environment setup guides
|
||||
- **Basic Knowledge**: Familiarity with Ruby, JavaScript, or the technology you want to work with
|
||||
|
||||
### Development Workflow
|
||||
|
||||
Our development workflow follows these steps:
|
||||
|
||||
1. **Find an Issue**: Look for issues tagged with "Good first issue" or create a new one
|
||||
2. **Fork the Repository**: Create your own copy of the Chatwoot repository
|
||||
3. **Create a Branch**: Make a feature branch for your changes
|
||||
4. **Make Changes**: Implement your fix or feature
|
||||
5. **Test Your Changes**: Ensure everything works correctly
|
||||
6. **Submit a Pull Request**: Open a PR with a clear description
|
||||
7. **Code Review**: Collaborate with maintainers to refine your changes
|
||||
8. **Merge**: Your contribution becomes part of Chatwoot!
|
||||
|
||||
## Before You Start
|
||||
|
||||
### 1. Check Existing Issues
|
||||
|
||||
Before starting work, check if someone else is already working on the same issue:
|
||||
|
||||
- Browse [open issues](https://github.com/chatwoot/chatwoot/issues)
|
||||
- Look for issues labeled "Good first issue" for beginners
|
||||
- Check if there's an existing pull request for the same feature
|
||||
|
||||
### 2. Create or Comment on an Issue
|
||||
|
||||
- **For new features**: Create an issue to discuss the feature before implementing
|
||||
- **For existing issues**: Comment that you'd like to work on it
|
||||
- **Wait for assignment**: This helps avoid duplicate work
|
||||
|
||||
### 3. Understand the Codebase
|
||||
|
||||
Familiarize yourself with:
|
||||
- **Architecture**: How Chatwoot is structured
|
||||
- **Coding Standards**: Our style guides and conventions
|
||||
- **Testing Practices**: How we write and run tests
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
### Branch Naming
|
||||
|
||||
Use descriptive branch names that follow our conventions:
|
||||
|
||||
```bash
|
||||
# Feature branches
|
||||
feature/issue-id-short-description
|
||||
feature/235-contact-panel
|
||||
|
||||
# Bug fix branches
|
||||
fix/issue-id-short-description
|
||||
fix/123-email-validation
|
||||
|
||||
# Chore branches
|
||||
chore/update-dependencies
|
||||
chore/improve-documentation
|
||||
```
|
||||
|
||||
### Commit Messages
|
||||
|
||||
Write clear, descriptive commit messages:
|
||||
|
||||
```bash
|
||||
# Good commit messages
|
||||
feat: Add contact search functionality (#235)
|
||||
fix: Resolve email validation issue (#123)
|
||||
docs: Update installation guide
|
||||
test: Add unit tests for contact model
|
||||
|
||||
# Avoid
|
||||
Update stuff
|
||||
Fix bug
|
||||
WIP
|
||||
```
|
||||
|
||||
### Pull Request Template
|
||||
|
||||
When creating a pull request, include:
|
||||
|
||||
**Description:**
|
||||
- Clear description of what the PR does
|
||||
- Link to related issues
|
||||
- Screenshots for UI changes
|
||||
|
||||
**Testing:**
|
||||
- How you tested the changes
|
||||
- Test cases covered
|
||||
- Any manual testing performed
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Self-review completed
|
||||
- [ ] Tests added/updated
|
||||
- [ ] Documentation updated
|
||||
- [ ] No breaking changes (or clearly documented)
|
||||
|
||||
### Example Pull Request
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Adds a new contact search feature that allows agents to quickly find contacts by name, email, or phone number.
|
||||
|
||||
Fixes #235
|
||||
|
||||
## Changes Made
|
||||
- Added search input to contact panel
|
||||
- Implemented backend search API
|
||||
- Added debounced search functionality
|
||||
- Updated contact list component
|
||||
|
||||
## Testing
|
||||
- Added unit tests for search API
|
||||
- Tested search with various input types
|
||||
- Verified performance with large contact lists
|
||||
- Manual testing on different browsers
|
||||
|
||||
## Screenshots
|
||||
[Include screenshots of the new feature]
|
||||
|
||||
## Checklist
|
||||
- [x] Code follows style guidelines
|
||||
- [x] Self-review completed
|
||||
- [x] Tests added
|
||||
- [x] Documentation updated
|
||||
- [x] No breaking changes
|
||||
```
|
||||
|
||||
## Code Standards
|
||||
|
||||
### Ruby/Rails Standards
|
||||
|
||||
- Follow [Ruby Style Guide](https://rubystyle.guide/)
|
||||
- Use [RuboCop](https://github.com/rubocop/rubocop) for linting
|
||||
- Write descriptive method and variable names
|
||||
- Add comments for complex logic
|
||||
- Follow Rails conventions
|
||||
|
||||
### JavaScript/Vue.js Standards
|
||||
|
||||
- Follow [JavaScript Standard Style](https://standardjs.com/)
|
||||
- Use [ESLint](https://eslint.org/) for linting
|
||||
- Write modular, reusable components
|
||||
- Use meaningful component and variable names
|
||||
- Follow Vue.js best practices
|
||||
|
||||
### Testing Standards
|
||||
|
||||
- Write tests for new features
|
||||
- Maintain or improve test coverage
|
||||
- Use descriptive test names
|
||||
- Test both happy path and edge cases
|
||||
- Mock external dependencies
|
||||
|
||||
## Development Environment
|
||||
|
||||
Choose your preferred development environment:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="macOS Setup" icon="apple" href="/contributing/environment-setup/macos">
|
||||
Set up development environment on macOS
|
||||
</Card>
|
||||
<Card title="Ubuntu Setup" icon="ubuntu" href="/contributing/environment-setup/ubuntu">
|
||||
Set up development environment on Ubuntu Linux
|
||||
</Card>
|
||||
<Card title="Windows Setup" icon="windows" href="/contributing/environment-setup/windows">
|
||||
Set up development environment on Windows
|
||||
</Card>
|
||||
<Card title="Docker Setup" icon="docker" href="/contributing/environment-setup/docker">
|
||||
Use Docker for consistent development environment
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Issue Labels
|
||||
|
||||
Understanding our issue labels helps you find the right issues to work on:
|
||||
|
||||
| Label | Description |
|
||||
|-------|-------------|
|
||||
| `good first issue` | Perfect for new contributors |
|
||||
| `help wanted` | Community help needed |
|
||||
| `bug` | Something isn't working |
|
||||
| `enhancement` | New feature or improvement |
|
||||
| `documentation` | Documentation improvements |
|
||||
| `question` | Further information requested |
|
||||
| `wontfix` | This will not be worked on |
|
||||
| `duplicate` | This issue already exists |
|
||||
|
||||
## Community Guidelines
|
||||
|
||||
### Be Respectful
|
||||
|
||||
- Treat everyone with respect and kindness
|
||||
- Be patient with new contributors
|
||||
- Provide constructive feedback
|
||||
- Help others learn and grow
|
||||
|
||||
### Communication
|
||||
|
||||
- Use clear, concise language
|
||||
- Ask questions when unsure
|
||||
- Share knowledge and resources
|
||||
- Be responsive to feedback
|
||||
|
||||
### Collaboration
|
||||
|
||||
- Work together towards common goals
|
||||
- Share credit for collaborative work
|
||||
- Help review others' contributions
|
||||
- Mentor new contributors
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you need help while contributing:
|
||||
|
||||
### Documentation
|
||||
- Read our comprehensive guides
|
||||
- Check the API documentation
|
||||
- Review existing code examples
|
||||
|
||||
### Community Support
|
||||
- **Discord**: [Join our community chat](https://discord.gg/cJXdrwS)
|
||||
- **GitHub Discussions**: [Ask questions and share ideas](https://github.com/chatwoot/chatwoot/discussions)
|
||||
- **Issues**: Create an issue for bugs or feature requests
|
||||
|
||||
### Maintainer Support
|
||||
- Tag maintainers in issues or PRs when needed
|
||||
- Be patient - maintainers are volunteers
|
||||
- Provide detailed information when asking for help
|
||||
|
||||
## Recognition
|
||||
|
||||
We value all contributions and recognize contributors in several ways:
|
||||
|
||||
- **Contributors Page**: Listed on our website and README
|
||||
- **Release Notes**: Mentioned in release announcements
|
||||
- **Social Media**: Highlighted on our social channels
|
||||
- **Swag**: Occasional contributor swag for significant contributions
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
All contributors must follow our [Code of Conduct](https://github.com/chatwoot/chatwoot/blob/develop/CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for everyone.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Ready to start contributing? Here's what to do next:
|
||||
|
||||
1. **Set up your development environment** using one of our setup guides
|
||||
2. **Find a good first issue** to work on
|
||||
3. **Fork the repository** and create a feature branch
|
||||
4. **Make your changes** following our guidelines
|
||||
5. **Submit a pull request** with a clear description
|
||||
|
||||
---
|
||||
|
||||
<Note>
|
||||
Remember, contributing to open source is a learning process. Don't be afraid to ask questions, make mistakes, and learn from the community. Every contribution, no matter how small, makes a difference!
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Start small with documentation improvements or bug fixes to get familiar with the codebase and contribution process before tackling larger features.
|
||||
</Tip>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,658 @@
|
||||
---
|
||||
title: Environment Variables for Development
|
||||
description: Complete guide to environment variables for Chatwoot development and testing
|
||||
sidebarTitle: Environment Variables
|
||||
---
|
||||
|
||||
# Environment Variables for Development
|
||||
|
||||
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
|
||||
|
||||
### Basic Development Configuration
|
||||
|
||||
Create your `.env` file from the example:
|
||||
|
||||
```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.
|
||||
@@ -0,0 +1,589 @@
|
||||
---
|
||||
title: Project Setup Guide
|
||||
description: Complete guide to setting up Chatwoot for development and contribution
|
||||
sidebarTitle: Setup Guide
|
||||
---
|
||||
|
||||
# Project Setup Guide
|
||||
|
||||
This comprehensive guide will walk you through setting up Chatwoot for development, from initial repository setup to running your first successful build.
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# Check Ruby version (should be 3.3.3)
|
||||
ruby --version
|
||||
|
||||
# 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
|
||||
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
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### 1. Environment File Setup
|
||||
|
||||
```bash
|
||||
# Copy the example environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Open the file for editing
|
||||
nano .env
|
||||
```
|
||||
|
||||
### 2. Basic Configuration
|
||||
|
||||
Update your `.env` file with the following essential settings:
|
||||
|
||||
```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
|
||||
foreman start -f Procfile.dev
|
||||
|
||||
# This starts:
|
||||
# - Rails server (port 3000)
|
||||
# - Webpack dev server
|
||||
# - Sidekiq worker
|
||||
```
|
||||
|
||||
### 2. Manual Startup
|
||||
|
||||
If you prefer to run services separately:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 3. Verify Installation
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
Email: john@acme.inc
|
||||
Password: Password1!
|
||||
```
|
||||
|
||||
### Creating Additional Users
|
||||
|
||||
```bash
|
||||
# Access Rails console
|
||||
bundle exec rails console
|
||||
|
||||
# Create a new user
|
||||
user = User.create!(
|
||||
name: "Your Name",
|
||||
email: "your.email@example.com",
|
||||
password: "Password123!",
|
||||
password_confirmation: "Password123!"
|
||||
)
|
||||
|
||||
# Make user an administrator
|
||||
user.account_users.first.update!(role: 'administrator')
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### 1. Code Quality Setup
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 2. Running Tests
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 3. Code Linting and Formatting
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## IDE Configuration
|
||||
|
||||
### VS Code Setup
|
||||
|
||||
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
|
||||
|
||||
```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)"
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Development Performance
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful 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
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
You're now ready to start developing with Chatwoot! Your development environment should be fully functional and ready for contribution.
|
||||
Reference in New Issue
Block a user