Twenty CRM: установка на свой сервер через Docker

Что потребуется

Официальный гайд называет минимум, без которого установка не имеет смысла: актуальные Docker и Docker Compose (конкретные номера версий в гайде не названы) и доступ к серверу — возможность создавать файлы и запускать команды.

По памяти официального минимума мало — на сервере живут сразу четыре сервиса (состав стека — ниже), поэтому практики советуют больше:

В гайде два варианта установки:

Шаг 0: Docker на чистом сервере

Сам гайд исходит из того, что Docker уже стоит. Если сервер пустой, поставьте Docker Engine и плагин Compose из официального репозитория Docker — так начинают туториалы Cloud.ru и WZ-IT. Последовательность из документации Docker (команды под root; с обычным пользователем добавьте sudo):

apt update && apt install ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
apt update
apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Готовность проверяется одной строкой: docker compose version.

Вариант 1: скрипт одной строкой

Скрипт скачивается из официального репозитория Twenty и запускается одной командой:

bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)

Если нужна конкретная версия — задайте переменную VERSION с полным тегом релиза:

VERSION=v2.38.1 bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)

Ограничения из гайда:

• принимаются только полные теги релизов — алиас latest не принимается;
• для релизов v2.9.0 и старее скрипт не работает.

Вариант 2: вручную через Docker Compose

Ручной путь — шесть шагов из официального гайда.

1. Скачайте файл переменных окружения:

   curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/.env.example

2. Сгенерируйте ключ шифрования и впишите его в ENCRYPTION_KEY:

   openssl rand -base64 32

3. Задайте пароль базы данных в PG_DATABASE_PASSWORD — без спецсимволов.
4. Скачайте compose-файл:

   curl -o docker-compose.yml https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/docker-compose.yml

5. Запустите контейнеры:

   docker compose up -d

6. Проверьте, что Twenty отвечает:

   curl http://localhost:3000

Команда из шага 5 поднимает не один контейнер, а стек из четырёх сервисов, как он описан в compose-файле гайда: server — само приложение, worker — фоновые задачи, PostgreSQL 16 — база данных, Redis — очереди. Разбор стека есть в туториале Cloud.ru. Отсюда и требования к памяти: четыре сервиса на двух гигабайтах тесно.

Диагностика после запуска

Если curl из шага 6 вернул HTML — приложение отвечает. Для более предметной проверки две команды:

docker compose ps

docker compose logs -f

Первая показывает статус каждого сервиса, вторая — логи вживую. Контейнер в статусе unhealthy чаще всего означает нехватку памяти или ошибку в переменных .env.

Доступ из интернета: переменная SERVER_URL

Без SERVER_URL Twenty доступен только с самого сервера. Это полный адрес, по которому CRM откроется из интернета, и складывается он из трёх частей: протокол (для публичного доступа — https), домен или IP-адрес сервера, порт — если нестандартный, его указывают явно. Пример: SERVER_URL=https://crm.vashdomen.ru.

После изменения переменной перезапустите контейнеры через docker compose down и docker compose up -d — простого restart недостаточно.

Домен и бесплатный SSL: nginx или Caddy

Из интернета Twenty открывает reverse proxy, а не сам контейнер. HTTPS нужен не для галочки: redirect URI для OAuth-входа задаётся по https, а настройка cookie AUTH_COOKIE_SAME_SITE=none требует HTTPS — оба пункта прописаны в документации. Бесплатного сертификата Let's Encrypt достаточно, и есть два рабочих пути.

nginx + certbot — путь из туториала Cloud.ru. Минимальный server block проксирует запросы на порт 3000:

server {
    listen 80;
    server_name crm.vashdomen.ru;

    location / {
        proxy_pass http://localhost:3000;
    }
}

Затем certbot выпустит сертификат Let's Encrypt и сам пропишет его в конфиг nginx:

certbot --nginx -d crm.vashdomen.ru

Caddy — вариант из гайда WZ-IT: конфиг умещается в две строки, а сертификаты Caddy получает и продлевает автоматически:

crm.vashdomen.ru {
    reverse_proxy localhost:3000
}

В обоих случаях сам Twenty остаётся на localhost:3000, наружу смотрит только proxy.

Безопасность сервера

• Firewall или security groups: снаружи открыты только порты 22, 80 и 443 — так настроен туториал Cloud.ru.
• Twenty запускают под отдельным пользователем в выделенной директории установки, а не из-под root — практика гайда WZ-IT.
• Порт 3000 наружу не открывают: к Twenty идут через proxy с SSL.

Обновления: новая версия без потери данных

Перед обновлением сделайте бэкап базы — гайд требует делать его всегда, команда в разделе ниже. Само обновление — три шага из гайда обновления:

1. Остановите Twenty:

   docker compose down

2. Поменяйте значение TAG в файле .env на тег нового релиза — ключевой шаг: без смены тега контейнеры поднимутся в прежней версии.
3. Запустите Twenty снова:

   docker compose up -d

Данные лежат в томах Docker и переживают обновление, миграции базы применяются автоматически при запуске — это описано в гайде обновления docs.twenty.com. Одна тонкость: начиная с релиза v2.34 Twenty требует PostgreSQL 15 или новее; в актуальном compose-файле уже PostgreSQL 16.

Бэкапы базы: pg_dump и расписание

В официальном гайде есть раздел про резервное копирование: базу выгружают pg_dump'ом и автоматизируют через crontab; там же описаны шаги восстановления. Команда из гайда (имена контейнера, пользователя и базы — из его примера):

docker exec twenty-postgres pg_dump -U postgres twenty > backup_$(date +%Y%m%d).sql

По расписанию — запись в crontab -e: в гайде выгрузка запускается каждый день в 02:00, дампы складываются в /backups/. Копии держите и вне сервера — в облаке или на другой машине.

Восстановление по гайду — сначала остановить сервисы, которые пишут в базу:

docker compose stop server worker

Затем накатить дамп и поднять всё обратно:

docker exec -i twenty-postgres psql -U postgres twenty < backup.sql

docker compose up -d

О чём важно не забыть

Самое серьёзное предупреждение гайда касается ENCRYPTION_KEY: потеряете ключ — потеряете все секреты, зашифрованные в базе данных. Храните его в надёжном месте. Если ключ скомпрометирован, его меняют по процедуре ротации — в документации Twenty есть отдельный раздел. Просто заменить строку в .env нельзя: данные не расшифруются.

Второе правило — менять в конфигурации только те настройки, которые описаны в гайде. Вложения — файлы из карточек — при желании переносят в S3-совместимое хранилище: в .env задаются endpoint, имя бакета и ключи доступа — рабочий пример приводят туториал Cloud.ru и разбор на Хабре.

Контейнеры из compose-файла гайда рассчитаны на продакшен и самохостинг; для вклада в разработку Twenty есть отдельная схема — Local Setup.

Что добавить к Twenty: коннектор мессенджеров

Twenty из коробки не слушает мессенджеры. Самовар CRM — коннектор, который разворачивается рядом: подключает Telegram (MTProto, обычный пользовательский аккаунт) и MAX (Bot API), создаёт контакты-Person из переписок, а LLM пишет резюме диалога и выставляет статус в карточке — читать всю переписку не нужно. Коннектор — тоже Docker-образ, ставится тем же способом. Первые два месяца — бесплатно. Замена облачной системе — на странице «аналог amoCRM и Битрикс24».

При подключении Самовара мы разворачиваем Twenty CRM и коннектор за вас. Инструменты с открытым исходным кодом размещаются на вашем сервере, а диалоги анализирует наша собственная обученная модель на основе KIMI 3. Первые два месяца — бесплатно, далее 3000 ₽ в месяц.

FAQ