QA Деск. Инструкция по установке

1. Варианты использования

QA Деск доступен в двух вариантах:

• Облачный сервис — установка не требуется: регистрация в кабинете app.qadesk.ru и, при необходимости, установка приложения на портал Битрикс24.
• Экземпляр на инфраструктуре заказчика — развёртывание дистрибутива средствами Docker Compose (раздел 4).

2. Начало работы с облачным сервисом

Облачный QA Деск начинает работу за 4 шага без установки: регистрация на app.qadesk.ru/register, подтверждение почты по ссылке, первый вход и мастер первых шагов. Вместо почты и пароля можно войти через Яндекс ID.

1. Откройте https://app.qadesk.ru/register.
2. Укажите адрес электронной почты и пароль. Также доступен вход через Яндекс ID.
3. Подтвердите адрес по ссылке из письма. Без подтверждения вход в кабинет не выполняется.
4. При первом входе автоматически создаётся личное рабочее пространство и запускается мастер первых шагов; по желанию разворачивается демо-проект с примерами кейсов и дефектов.

3. Установка приложения на портал Битрикс24

Приложение QA Деск ставит администратор портала Битрикс24 и выбирает рабочие группы для интеграции. После установки в карточке задачи появляется вкладка «Баги», сотрудники выбранных групп попадают в пространство с ролями по должностям, вход в кабинет — сквозной с портала.

1. Установите приложение QA Деск на портал (установку выполняет администратор портала). Если портала ещё нет — его можно создать бесплатно.
2. В мастере установки выберите рабочие группы портала, для которых включается интеграция. Сотрудники выбранных групп синхронизируются в рабочее пространство QA Деск, роли назначаются по правилам соответствия должностей.
3. После установки в карточках задач портала появляется вкладка «Баги», а вход сотрудников в кабинет выполняется сквозным образом с портала.

4. Развёртывание экземпляра на своей инфраструктуре

Экземпляр QA Деск разворачивается средствами Docker Compose из 4 служб: PostgreSQL 16, сервер приложения, сервис приёма отчётов и обратный прокси Caddy с TLS. Нужен сервер Linux с Docker Engine и Docker Compose v2, рекомендуется от 2 vCPU и 4 ГБ ОЗУ.

4.1. Состав поставки

Дистрибутив включает файл docker-compose, конфигурацию обратного прокси и инструкцию по получению образов. Состав служб:

Дистрибутив предоставляется по запросу: hello@qadesk.ru.

4.2. Требования

• Сервер Linux (проверено на Ubuntu 24.04), от 2 vCPU и 4 ГБ ОЗУ, от 20 ГБ диска.
• Docker Engine и Docker Compose v2.
• Доменное имя, указывающее на сервер (для автоматического выпуска TLS-сертификатов).

4.3. Порядок установки

1. Распакуйте дистрибутив на сервере.
2. Заполните файл окружения .env.prod по образцу из поставки: пароль СУБД (POSTGRES_PASSWORD), доменные имена, реквизиты почтового сервиса для писем подтверждения и восстановления пароля.
3. Запустите службы:

   docker compose -f infra/docker-compose.prod.yml up -d --build

4. Миграции схемы базы данных применяются автоматически при старте сервера приложения.

4.4. Вход через LDAP / Active Directory

Сотрудники входят доменной учётной записью: на экране входа появляется форма «логин и пароль домена». Пароль проверяется самим каталогом и в QA Деск не хранится. Вход настраивается в .env.prod:

LDAP_URL=ldaps://dc.company.ru
LDAP_BIND_DN=CN=svc-qadesk,OU=Service,DC=company,DC=ru
LDAP_BIND_PASSWORD_FILE=/run/secrets/ldap-bind
LDAP_USER_BASE=OU=Staff,DC=company,DC=ru
LDAP_TLS_CA_FILE=/run/secrets/company-root-ca.pem
LDAP_WORKSPACE_ID=<id рабочего пространства>
LDAP_GROUP_ROLES=[{"group":"CN=QA-Admins,OU=Groups,DC=company,DC=ru","role":"admin"},
                  {"group":"CN=QA,OU=Groups,DC=company,DC=ru","role":"qa"},
                  {"group":"CN=Developers,OU=Groups,DC=company,DC=ru","role":"dev"}]

• Сервисная учётка (LDAP_BIND_DN) — только чтение записей сотрудников и групп.
• Логин по умолчанию ищется в sAMAccountName, userPrincipalName, mail и uid; другой фильтр задаётся LDAP_USER_FILTER с подстановкой {login}.
• Роли назначаются по группам в пространстве LDAP_WORKSPACE_ID: порядок правил — приоритет, сотрудник в нескольких группах получает роль первого совпавшего правила. LDAP_DEFAULT_ROLE — роль для тех, кто не попал ни в одну группу; без неё такие сотрудники не входят. Роль пересчитывается при каждом входе и может как повыситься, так и понизиться; роли, назначенные вручную в кабинете, вход не меняет.
• Шифрование: ldaps:// или LDAP_STARTTLS=true; сертификат каталога проверяется, корневой сертификат организации — в LDAP_TLS_CA_FILE. Незашифрованный ldap:// экземпляр считает ошибкой конфигурации.

Работоспособность входа видна в точке готовности (раздел 5): при отвергнутой сервисной учётке или ошибке в настройках в broken появится auth-ldap, при недоступном каталоге — в degraded.

5. Проверка работоспособности

Экземпляр QA Деск готов, когда ответ GET /health/ready содержит "broken": []. Проверяется тело ответа служебной точки готовности, а не код HTTP 200:

curl -s https://<ваш-домен>/health/ready

Экземпляр готов, когда в ответе "broken": [] — список неработающих подсистем пуст:

{"status":"ok","service":"qadesk-api","db":"ok","degraded":[],"broken":[]}

Непустой список broken называет отказавшую подсистему; список degraded — подсистемы, работающие в ограниченном режиме (например, не настроенный вход через Яндекс ID). После проверки готовности откройте кабинет в браузере и выполните регистрацию первого пользователя.