Пошаговая инструкция · Самостоятельная установка
Как установить Chatwoot на сервер: поддержка клиентов через сайт
Пошаговая инструкция для самостоятельной установки. Установим Chatwoot Community на Ubuntu 26.04: отдельно настроим базу, HTTPS и почту, создадим команду и проверим первый разговор с посетителем.
Что понадобится и где выполнять команды #
Установим Chatwoot Community 4.18.0 для обращений с сайта. Веб-приложение показывает переписку, Sidekiq выполняет фоновые задачи, PostgreSQL хранит сообщения, Redis — очереди. До создания владельца ограничьте доступ к HTTPS своим IP в сетевом экране провайдера: первый посетитель не должен занять вашу установку. Порт 80 оставьте доступным для сертификата.
Подготовьте отдельный сервер Ubuntu 26.04 LTS по общей инструкции: доступ по SSH, Docker Engine, Docker Compose и Nginx. Docker запускает приложение в контейнерах — отдельных окружениях с нужными зависимостями. Compose читает файл, в котором описаны все контейнеры и их связи. Nginx будет принимать HTTPS-запросы из браузера и передавать их приложению.
Все команды выполняйте в SSH-терминале сервера. Домен chat.example.com в примерах заменяйте своим. В DNS-панели создайте A-запись с публичным IPv4 сервера; проверьте её командой getent ahostsv4 chat.example.com. Без правильного адреса сертификат не будет выпущен. Нужны входящие порты 80/443 и SSH; базы данных снаружи не открывайте. Выбор сервера для Chatwoot поможет рассчитать ресурсы.
Перед работой выполните docker compose version: команда должна показать Compose v2. Если доступ к Docker запрещён, завершите настройку доступа из общей инструкции и заново войдите по SSH. В nano файл сохраняется клавишами Ctrl+O и Enter, редактор закрывается Ctrl+X. Примеры конфигурации записывают в файл, а не запускают как команды.
Настройка внешнего доступа использует обратный прокси Nginx и Certbot для Nginx. Приложение остаётся доступным на локальном порту; снаружи открыт его HTTPS-домен.
WebSocket и заголовки сверены с официальным примером Nginx Chatwoot.
Шаг 1. Создайте папку установки #
Отдельная папка будет хранить Compose и настройки. umask 077 ограничивает доступ к новым файлам вашим пользователем.
mkdir -p "$HOME/apps/chatwoot"
cd "$HOME/apps/chatwoot"
umask 077Дальнейшие команды выполняйте из этой папки. После нового подключения сначала выполняйте cd "$HOME/apps/chatwoot".
Шаг 2. Скачайте файлы одного релиза #
Возьмём официальный шаблон настроек и Compose из v4.18.0. Первый файл содержит переменные приложения, второй описывает сервисы. curl не запускает скачанные файлы.
curl -fL https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/.env.example -o .env
curl -fL https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/docker-compose.production.yaml -o compose.yamlОбе загрузки должны завершиться успешно. Если одна вернула ошибку, не продолжайте с неполным набором файлов.
Шаг 3. Закрепите образ и уберите публичные порты базы #
Следующая команда редактирует только Compose: выбирает Community-образ 4.18.0, Redis 7 и пароль PostgreSQL из .env. Убирает публикацию портов PostgreSQL и Redis: они будут доступны контейнерам по внутренней сети. Это один блок Python, скопируйте его целиком вместе с первой и последней строками.
python3 - <<'PATCH'
from pathlib import Path
p = Path('compose.yaml')
s = p.read_text().replace('chatwoot/chatwoot:latest', 'chatwoot/chatwoot:v4.18.0-ce')
s = s.replace('redis:alpine', 'redis:7-alpine')
s = s.replace(" ports:\n - '127.0.0.1:5432:5432'\n", '')
s = s.replace(" ports:\n - '127.0.0.1:6379:6379'\n", '')
s = s.replace('- POSTGRES_PASSWORD=', '- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}')
p.write_text(s)
PATCHКоманда должна завершиться без traceback. Если ошибка есть, восстановите Compose загрузкой из предыдущего шага и проверьте, что копировали весь блок.
Шаг 4. Получите три разных секрета #
Сгенерируйте значения для ключа приложения, пароля PostgreSQL и пароля Redis. Каждая строка вывода — отдельное случайное значение. Сохраните их в менеджере паролей с подписями. Значения понадобится вставить на следующем шаге.
openssl rand -hex 64
openssl rand -hex 32
openssl rand -hex 32Должны получиться три строки. Не используйте один пароль для всех назначений и не оставляйте шаблонные значения.
Шаг 5. Заполните основные настройки приложения #
Откройте nano .env. Найдите перечисленные параметры и замените их значения; остальные строки сохраняйте. Вставьте свои секреты, а домен замените своим. ENABLE_ACCOUNT_SIGNUP=true нужен только для первого аккаунта: закроем регистрацию сразу после его создания.
Сохраните файл: Ctrl+O, Enter, Ctrl+X. ACTIVE_STORAGE_SERVICE=local хранит вложения в томе Docker; его включим в копию вместе с базой.
SECRET_KEY_BASE=ВСТАВЬТЕ_ПЕРВЫЙ_СЕКРЕТ
POSTGRES_HOST=postgres
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=ВСТАВЬТЕ_ВТОРОЙ_СЕКРЕТ
POSTGRES_DATABASE=chatwoot_production
REDIS_PASSWORD=ВСТАВЬТЕ_ТРЕТИЙ_СЕКРЕТ
REDIS_URL=redis://redis:6379
FRONTEND_URL=https://chat.example.com
FORCE_SSL=true
ACTIVE_STORAGE_SERVICE=local
ENABLE_ACCOUNT_SIGNUP=trueПроверьте, что домен и все три секрета заменены. Ни одна из строк не должна дублировать уже существующий параметр.
Шаг 6. Настройте исходящую почту #
SMTP — способ отправки писем через почтового провайдера. В том же nano .env задайте данные своего сервиса. Пример использует STARTTLS на порту 587: соединение переходит на шифрование перед отправкой. Для другого режима используйте требования провайдера. Сохраните файл теми же клавишами.
MAILER_SENDER_EMAIL=Поддержка <support@example.com>
SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=support@example.com
SMTP_PASSWORD=ВСТАВЬТЕ_ПАРОЛЬ_SMTP
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=trueИспользуйте разрешённый адрес отправителя. Не оставляйте чужой домен chatwoot.com или example.com. Пароль SMTP отличается от секретов приложения.
Шаг 7. Проверьте конфигурацию до запуска #
Ограничим чтение файла с секретами и попросим Compose проверить структуру конфигурации. --quiet не печатает секреты в терминал.
chmod 600 .env
docker compose config --quietПри успехе вывода не будет. Если Compose сообщает о переменной или отступах, исправьте файл до загрузки и запуска контейнеров.
Шаг 8. Скачайте образы контейнеров #
Образ — готовый комплект приложения и зависимостей. Сейчас Docker скачает выбранные версии; сами сервисы ещё не запускаются.
docker compose pullВсе образы должны загрузиться без denied или not found. При ошибке проверьте доступ к реестру и имя выбранного тега.
Шаг 9. Запустите базу и очередь #
Сначала запустим PostgreSQL и Redis: они нужны для подготовки данных Chatwoot. Флаг -d оставляет сервисы работать в фоне.
docker compose up -d postgres redisКоманда должна завершиться успешно. Если контейнер перезапускается, посмотрите docker compose logs --tail=60 postgres redis и исправьте ошибку.
Шаг 10. Создайте структуру базы Chatwoot #
db:chatwoot_prepare создаёт таблицы и служебные данные. Контейнер rails запускается временно и удаляется после выполнения. Не заменяйте эту команду обычной миграцией: для первой установки нужен штатный prepare.
docker compose run --rm rails bundle exec rails db:chatwoot_prepareДождитесь завершения без ошибки. При отказе подключения проверьте POSTGRES_*; при ошибке расширения — официальный образ PostgreSQL с pgvector. Веб-приложение до успеха не запускайте.
Шаг 11. Запустите приложение и фоновые задачи #
Теперь можно включить Rails и Sidekiq. Оба должны использовать один и тот же релиз и настройки: иначе интерфейс и обработка писем могут расходиться.
docker compose up -d rails sidekiqПроверьте docker compose ps: Rails и Sidekiq должны работать, а не постоянно перезапускаться. Первое открытие может потребовать немного времени.
Шаг 12. Проверьте ответ приложения внутри сервера #
Порт 3000 опубликован только на localhost — внутреннем адресе этой машины. Команда проверяет приложение без участия домена и Nginx.
curl -I http://127.0.0.1:3000HTTP-ответ 200 или перенаправление на вход показывает, что приложение доступно. Connection refused или 500 исправляйте по docker compose logs --tail=100 rails; настройку HTTPS пока отложите.
Шаг 13. Сохраните сайт Nginx #
Установите Nginx и Certbot по подготовке Ubuntu, если ещё не установили. Откройте sudo nano /etc/nginx/sites-available/chatwoot и вставьте файл ниже. Замените все домены своими. Nginx передаёт приложению домен, адрес клиента и протокол; Upgrade и Connection сохраняют WebSocket. До получения сертификата условие $scheme блокирует обычные HTTP-запросы кодом 403, чтобы вход не происходил без шифрования.
/etc/nginx/sites-available/chatwootmap $http_upgrade $chatwoot_connection_upgrade {
default upgrade;
"" close;
}
server {
listen 80;
server_name chat.example.com;
client_max_body_size 100m;
location / {
if ($scheme = http) { return 403; }
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $chatwoot_connection_upgrade;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_buffering off;
}
}
Сохраните Ctrl+O, Enter, Ctrl+X. В файле пока нет путей к сертификатам: Nginx сможет проверить его до выпуска HTTPS.
Шаг 14. Подключите сайт и проверьте HTTP #
Ссылка подключает сохранённый сайт. nginx -t проверяет все настройки сервера; && разрешает перечитать их только при успешной проверке. curl проверяет ответ для вашего домена. При ошибке остановитесь, исправьте указанную строку и повторите проверку.
sudo ln -sfn /etc/nginx/sites-available/chatwoot /etc/nginx/sites-enabled/chatwoot
sudo nginx -t && sudo systemctl reload nginx
curl -I http://chat.example.com/Ожидается successful от nginx -t и HTTP 403 для обычного запроса: до HTTPS это намеренная блокировка. DNS должен указывать на сервер, TCP 80/443 — быть доступен у провайдера. Ничего не вводите в форму входа по HTTP.
Шаг 15. Получите сертификат и включите HTTPS #
Каждое имя из команды должно указывать на этот сервер. Certbot проверит домены, сам добавит сертификат в сайт Nginx и включит перенаправление HTTP → HTTPS. Укажите свою почту при запросе и подтвердите условия Let’s Encrypt. Это отдельное действие после успешной проверки HTTP.
sudo /snap/bin/certbot --nginx -d chat.example.com --redirectCertbot сообщил об успешной установке. Откройте HTTPS-адрес со своего компьютера: браузер не должен предупреждать о сертификате. Для закрытой панели используйте разрешённый IP. При ошибке исправьте DNS, в том числе AAAA, либо доступ к TCP 80; не повторяйте запросы выпуска подряд.
Шаг 16. Проверьте продление сертификата #
Certbot из snap создаёт службу автоматического продления. Dry-run выполняет пробное продление: настоящие сертификаты не заменяются. Затем проверьте, что таймер планирует следующий запуск. Сохраняйте доступ к TCP 80 для следующих проверок домена.
sudo /snap/bin/certbot renew --dry-run
systemctl list-timers --all 'snap.certbot.renew*'Пробное продление успешно, у таймера есть следующий запуск. Если тест не прошёл, проверьте /var/log/letsencrypt/letsencrypt.log; сначала исправьте причину. После этого можно создавать учётную запись и приглашать пользователей.
Шаг 17. Создайте владельца организации #
В браузере зарегистрируйте первый аккаунт с собственной рабочей почтой и отдельным длинным паролем. Создайте организацию. Это пользователь, который будет приглашать сотрудников и управлять каналами.
Выйдите и войдите снова. Убедитесь, что у вас сохранился доступ к почте владельца и пароль записан безопасно.
Шаг 18. Закройте регистрацию новых организаций #
В терминале откройте nano .env, измените ENABLE_ACCOUNT_SIGNUP на false и сохраните файл. Затем пересоздайте Rails и Sidekiq, чтобы они прочитали новое окружение.
docker compose up -d --force-recreate rails sidekiqПроверьте в приватном окне браузера, что посторонний не может создать отдельный аккаунт организации. Ваш вход должен продолжать работать.
Шаг 19. Пригласите первого сотрудника #
В своём аккаунте отправьте приглашение второму сотруднику. Он должен открыть письмо и войти под собственной учётной записью. Это проверяет сразу отправку через SMTP и выполнение задачи Sidekiq. После успеха можно убрать временное ограничение HTTPS по IP.
Письмо должно прийти, а сотрудник — войти в нужную организацию. Если доставки нет, проверьте папку «Спам», параметры SMTP и docker compose logs --tail=100 sidekiq.
Шаг 20. Проверьте разговор через виджет сайта #
Создайте Inbox с каналом Website и добавьте сотрудников, которым разрешено отвечать. Inbox — ящик обращений одного канала. Скопируйте выданный системой скрипт на тестовую страницу своего сайта. В другом браузере отправьте сообщение и небольшое вложение, затем ответьте из Chatwoot.
Посетитель должен увидеть ответ, сотрудник — сообщение и вложение. Закройте и снова откройте обращение: история должна сохраниться. Другие каналы подключайте только после этого теста, по их отдельным требованиям.
Шаг 21. Сохраните базу переписки #
Создадим папку копии и коротко остановим Rails и Sidekiq, чтобы сообщения и вложения не менялись при копировании. Предупредите команду о перерыве. Следующий шаг выполняйте в том же SSH-сеансе. При любой ошибке верните сервисы командой docker compose start rails sidekiq.
umask 077
CHATWOOT_BACKUP="$HOME/backups/chatwoot/$(date -u +%Y%m%dT%H%M%SZ)"
mkdir -p "$CHATWOOT_BACKUP"
docker compose stop rails sidekiq
docker compose exec -T postgres pg_dump -U postgres chatwoot_production > "$CHATWOOT_BACKUP/database.sql"Команда pg_dump должна завершиться без ошибки. Пустой файл либо отказ подключения нельзя считать копией.
Шаг 22. Сохраните вложения и верните работу #
В ту же папку добавим вложения и настройки. Затем запустим приложение обратно. Скопируйте всю папку CHATWOOT_BACKUP через SFTP в закрытое хранилище за пределами сервера.
docker compose cp rails:/app/storage "$CHATWOOT_BACKUP/storage"
cp .env compose.yaml "$CHATWOOT_BACKUP/"
docker compose start rails sidekiq
ls -lh "$CHATWOOT_BACKUP"Проверьте наличие SQL, storage, .env и compose.yaml. Откройте сайт и прежнее вложение. Архив содержит ключи и переписку, поэтому доступ к копии должен быть ограничен.
Если возникла ошибка или пора обновляться #
Команды Compose работают из каталога $HOME/apps/chatwoot. Посмотрите состояние через docker compose ps --all и последние сообщения через docker compose logs --tail=100 rails sidekiq postgres redis. Не запускайте всю установку заново при первой ошибке: сначала найдите конкретный сервис и сообщение. 502 в браузере обычно означает, что Nginx не может получить ответ приложения; сначала проверьте локальный адрес из инструкции.
Для проверки восстановления используйте отдельный сервер с теми же образами, восстановите базу и /app/storage, сохранив .env с прежним SECRET_KEY_BASE. На тестовом сервере отключите внешние каналы и отправку рабочих писем. Перед включением MFA — входа с дополнительным подтверждением — настройте постоянные ключи ACTIVE_RECORD_ENCRYPTION_* по официальным переменным и включите их в копию: менять их после шифрования данных нельзя.
Перед обновлением сохраните свежую полную копию, выберите конкретный релиз и прочитайте его примечания. Проверяйте обновление на отдельной машине с восстановленной копией. Если меняется схема базы, возврат одного старого образа не заменяет возврат совместимого дампа. Менять основную версию базы отдельным тегом без процедуры переноса данных нельзя.
Настройки внешнего доступа храните вместе с копией приложения: /etc/nginx/sites-available/chatwoot и /etc/letsencrypt содержат сайт и сертификаты с закрытыми ключами. Архивируйте их с sudo в закрытое хранилище. После восстановления подключите сайт через sites-enabled, выполните sudo nginx -t, затем перечитайте Nginx. Для ошибки 502 сначала проверьте локальное приложение и /var/log/nginx/error.log; для сертификата — /var/log/letsencrypt/letsencrypt.log и таймер продления.