DTPulseДокументация on-prem

DTPulse on-prem

Self-hosted DTPulse — полная функциональность нашего SaaS dtpulse.ru, развёрнутая на вашей инфраструктуре. Один Docker-стек, лицензионный ключ, периодический phone-home к нашему license-серверу для проверки валидности.

Требования

  • Linux-хост (любой дистрибутив с поддержкой Docker)
  • Docker 24+ и Docker Compose v2
  • 4 ГБ RAM, 20 ГБ свободного места на диске
  • Открытые порты 80 и 443 из публичного интернета (Caddy автоматически выпускает TLS-сертификаты через Let's Encrypt)
  • DNS A/AAAA-запись, указывающая на этот хост
  • Исходящий HTTPS к dtpulse.ru только на этапе установки — /api/license/redeem биндит ключ к instanceId этого хоста. После установки instance работает полностью офлайн весь срок действия лицензии: ключ HMAC-подписан с встроенным expiresAt, plan и maxEmployees, проверка идёт локально без обращения к нашему серверу.
Air-gapped после установки. Опциональный лицензионный heartbeat по умолчанию выключен (env LICENSE_HEARTBEAT_ENABLED не задан). Если хочется автоматических продлений и возможности удалённого отзыва ключа — включается env-флагом; рекомендуемая частота — раз в день, не в час. Для полностью air-gapped установок (нет интернета и при первой установке тоже) — обратитесь в отдел продаж за заранее привязанным ключом.

Быстрая установка (10 минут)

Установка одной командой:

sh -c "$(curl -fsSL https://dtpulse.ru/install)"

Инсталлятор спросит:

  • Лицензионный ключ — токен dtp_op_…, выдан вам отделом продаж. Сразу проверяется на license-сервере: отозванные, опечатанные или ключи для другой платформы выдают ошибку и инсталлятор снова просит ключ — установка не пойдёт дальше с неправильным ключом.
  • Email администратора — логин первого администратора
  • Название компании — отображается в интерфейсе и письмах
  • HTTP-порт — по умолчанию 80; можно выбрать другой (например, 8080), если 80 занят
  • SMTP host / user / password / from — для приглашений, восстановления пароля, уведомлений об истечении лицензии (можно пропустить, но настоятельно рекомендуем настроить сразу)
  • Yandex Maps API key — ключ от developer.tech.yandex.ru; если пропустить, карты будут использовать OpenStreetMap

Инсталлятор скачает Docker-образы, поднимет стек и напечатает одноразовый пароль администратора прямо в выводе между маркерами SEED_CREDENTIALS. Всё занимает 2–5 минут на свежей VPS.

Перед запуском: Linux-хост с Docker 24+ и Docker Compose v2. Если Docker не установлен:

curl -fsSL https://get.docker.com | sh

Расширенный инсталлятор (с доменом + Caddy + автоматическим TLS) — если у вас уже есть домен и нужен HTTPS с первого старта, запросите у отдела продаж production-инсталлятор: он сразу поднимает Caddy с Let's Encrypt. Команда выше — HTTP-only по голому IP, для тестового запуска.

Первый вход

1. Откройте https://ваш-домен.ру/ (TLS автоматически выпустит Caddy)
2. Войдите с email администратора и одноразовым паролем из вывода инсталлятора
3. Приложение сразу попросит сменить пароль

Не успели сохранить одноразовый пароль? Вытащите из логов:

cd /opt/dtpulse
docker compose logs app | grep -A4 SEED_CREDENTIALS

(Работает пока логи не ротировались. Если SMTP настроен, на /signin доступна форма «Забыли пароль?».)

Настройка почты

Инсталлятор спрашивает SMTP сразу — если вы пропустили этот шаг, приложение работает, но:

  • Приглашения не отправляются
  • Восстановление пароля сломано (риск блокировки, если админ забудет пароль)
  • Уведомления о согласовании отсутствий не приходят
  • Предупреждения об истечении лицензии не дойдут — узнаете о проблеме в день блокировки доступа, а не за 14 дней. Главная причина не пропускать настройку SMTP.

Чтобы добавить SMTP позже — отредактируйте /opt/dtpulse/.env:

SMTP_HOST=smtp.yandex.ru        # либо mail.ru, ваш собственный Postfix и т.п.
SMTP_PORT=465
SMTP_USER=noreply@yourcompany.ru
SMTP_PASS=ваш-пароль-или-API-key
EMAIL_FROM=DTPulse noreply@yourcompany.ru

Затем перезапустите контейнер:

cd /opt/dtpulse && docker compose restart app

Проверьте: в DTPulse зайдите в /admin/staff, отправьте приглашение себе на другой email, убедитесь что письмо пришло. Если нет — посмотрите логи:

docker compose logs app | grep -i 'email\|smtp'

SSO (опционально)

DTPulse поддерживает SAML 2.0 (Okta, Azure AD, Google Workspace, OneLogin, Keycloak, ADFS). Настройка — /admin/integrations после первого входа. Конфигурация per-tenant, env-переменные не нужны.

Карты (Yandex Maps API key)

CityPicker в карточках сотрудников и страница /map (офисы + сотрудники по городам) используют Yandex.Карты. Без API-ключа автоматически переключаются на OpenStreetMap. Чтобы включить Яндекс:

1. Получите ключ — зайдите на developer.tech.yandex.ru, войдите под своим Yandex-аккаунтом (НЕ общим с поставщиком — биллинг привязан к владельцу ключа).
2. Нажмите «Подключить API» → выберите «JavaScript API и HTTP Геокодер».
3. В разделе «HTTP Referer» добавьте домен вашей инсталляции (например, dtpulse.yourcompany.ru или *.yourcompany.ru). Без правильного referer Yandex отказывается загружать тайлы и карта остаётся пустой.
4. Скопируйте ключ (выглядит как aB1cD2ef-3456-7890-abcd-ef1234567890).
5. Добавьте в /opt/dtpulse/.env:

echo 'YANDEX_MAPS_API_KEY=aB1cD2ef-3456-7890-abcd-ef1234567890' >> /opt/dtpulse/.env
   cd /opt/dtpulse && docker compose restart app

6. Жёстко обновите открытую вкладку (⌘+Shift+R / Ctrl+Shift+R) — карта должна показать тайлы Яндекса с русскими подписями и копирайтом Yandex в углу.

Важно — не используйте чужие ключи (включая наши). Ключ привязан к конкретному домену (Yandex блокирует запросы с других хостов) и расход API биллится на аккаунт владельца ключа. Нужен ваш собственный.

Смена домена после установки

Если вы установили на одно имя (IP, dtpulse.staging.example.ru и т.п.) и позже хотите переехать на другое — обновите NEXTAUTH_URL и перезапустите:

cd /opt/dtpulse
sed -i 's|^NEXTAUTH_URL=.*|NEXTAUTH_URL=https://new-domain.example.ru|' .env
sed -i 's|^DOMAIN=.*|DOMAIN=new-domain.example.ru|' .env
docker compose up -d app caddy

Зачем это важно: все письма (восстановление пароля, верификация email, согласования отсутствий, уведомления, приглашения на ревью) собирают ссылки как ${NEXTAUTH_URL}/.... Если NEXTAUTH_URL остался указывать на старое имя — пользователи получат письма со ссылками на хост, который больше не обслуживает приложение, а токены reset/verify хранятся в локальной БД (открыть их с другого хоста нельзя). Приложение пишет warning при старте, если NEXTAUTH_URL пуст или указывает на наш SaaS-домен:

docker compose logs app | grep '\[on-prem startup\]'

Бэкапы

Два тома для бэкапа:

  • pgdata — данные Postgres (всё: тенанты, сотрудники, статьи KB и т.д.)
  • ./data/ — runtime-файлы (license cache, initial credentials)

Рекомендуется ночной pg_dump:

docker compose exec db pg_dump -U dtpulse dtpulse | gzip > backups/$(date +%F).sql.gz

Обновления

cd /opt/dtpulse && docker compose pull && docker compose up -d

Стянет последний опубликованный образ, перевыкатит app + cron-контейнеры. Данные Postgres и конфиги сохраняются. Миграции применяются автоматически; если миграция падает — docker-compose оставляет работать предыдущий контейнер, безопасный rollback.

Чтобы зафиксировать конкретную версию вместо :latest, отредактируйте .env:

IMAGE_TAG=v1.4.2

Продление лицензии

У лицензии есть дата окончания. Приложение шлёт email админам за 14 дней, за 7 дней и в день истечения; ещё 30 дней работает в льготном режиме, после чего вход блокируется. Данные не удаляются ни на каком этапе — ввод нового ключа на странице /blocked (или через продажи по email) восстанавливает доступ мгновенно.

Продление: запросите новый ключ у sales@dtpulse.ru, затем либо:

  • Отредактируйте LICENSE_KEY в .env и docker compose restart app
  • Либо, если уже заблокировано, вставьте новый ключ на странице /blocked

Поиск проблем

Инсталлятор отказывается принимать лицензионный ключ:

  • Couldn't reach the license server — исходящий HTTPS к dtpulse.ru заблокирован на этом хосте на момент redeem'а. Откройте egress для dtpulse.ru:443 единоразово и повторите ввод ключа; после этого порт можно закрывать обратно — для рантайма он не нужен.
  • Key not recognized — опечатка, либо вы используете ключ, выпущенный для другой платформы. Перепроверьте ключ, отправленный продажами; он должен начинаться с dtp_op_.
  • This key was revoked / already bound to another installation — обратитесь в продажи за заменой или перепривязкой ключа при легитимной миграции на новую VPS.

Сайт не открывается (нет TLS, нет ответа):

  • DNS: проверьте что домен указывает на этот хост:
dig +short ваш-домен.ру
  • Firewall: открыты ли порты 80 и 443:
sudo ufw status
  • Логи Caddy:
docker compose logs caddy

Сразу после установки появляется страница /blocked:

  • License-сервер недоступен с этого хоста
  • Проверка:
curl https://dtpulse.ru/api/license/verify
  • Убедитесь что LICENSE_KEY в env соответствует ключу, выданному продажами

Одноразовый пароль админа не показан / уже прокрутился:

  • Вытащите из логов:
docker compose logs app | grep -A4 SEED_CREDENTIALS
  • Если логи ротировались — используйте «Забыли пароль?» на /signin (требуется настроенный SMTP).

Падают подключения к БД после перезагрузки хоста:

  • Postgres стартует раньше Docker; restart: unless-stopped обычно справляется. Если нет:
docker compose restart

Поддержка

  • Продажи / продление лицензии: sales@dtpulse.ru
  • Сообщения об уязвимостях: security@dtpulse.ru