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

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

Версия 1.4Обновлено: 14.11.2026ООО «Эм Си Арт РУС»

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 и выбирает рабочие группы для интеграции. После установки в карточке задачи появляется вкладка «QA Деск: дефекты», сотрудники выбранных групп попадают в пространство с ролями по должностям, вход в кабинет — сквозной с портала.

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

3.1. Локальное приложение вместо Маркета

Если политика портала допускает только собственные приложения или подписки с Маркетом нет, QA Деск подключается как локальное приложение портала со своей парой ключей: client_id и client_secret выдаёт сам портал, и они действуют только для него. Администратор пространства QA Деск (право «Управление интеграциями») выполняет шаги по порядку.

  1. В кабинете QA Деск откройте «Интеграции → Битрикс24» и нажмите «Создать» в блоке «Локальное приложение». Появятся два адреса с ключом установки, список прав и мест встраивания.
  2. На портале откройте «Приложения → Ресурсы для разработчиков → Другое → Локальное приложение». Вставьте «Путь вашего обработчика» и «Путь для первоначальной установки», отметьте перечисленные права, сохраните. Портал выдаст client_id и client_secret.
  3. Введите выданные ключи в блоке «Локальное приложение» и сохраните. Секрет хранится в зашифрованном виде и назад не показывается.
  4. На портале установите приложение. QA Деск проверяет, что присланные порталом токены выданы именно этой парой; при несовпадении установка отклоняется, портал в QA Деск не появляется.
Ключ установки входит в оба адреса и выбирает вашу пару ключей — не публикуйте адреса. «Перевыпустить ключ» меняет адреса, пока приложение не установлено; чтобы сменить ключи у установленного приложения, удалите его на портале и установите заново. Если на портале уже установлено приложение QA Деск из Маркета, сначала удалите его на портале: тиражное и локальное приложение на одном портале не работают, установка локального отклонит такой портал. Ограничение Битрикс24: раздел «Маркет» в мобильном приложении показывает только решения, установленные из Маркетплейса, — локальное приложение там не появится; в браузере и в карточках задач оно работает так же.

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

Коробка QA Деск — те же образы сервера приложения, сервиса приёма отчётов и кабинета, что работают в облаке, плюс PostgreSQL 16 в одном проекте Docker Compose. Ставится одной командой из офлайн-архива, без доступа к интернету и реестрам образов. Нужен сервер Linux x86-64 от 2 vCPU и 4 ГБ ОЗУ.

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

Архив qadesk-box-<версия>.tar.gz: образы контейнеров (images/), файл docker-compose.yml, конфигурация обратного прокси, установщик install.sh, приёмочная проверка smoke.sh, инструкция и контрольные суммы SHA256SUMS. Состав служб:

СлужбаНазначениеПорт
postgresPostgreSQL 16 (официальный образ, версия закреплена)внутренний
apiСервер приложения (Node.js/NestJS)внутренний 3000
ingestСервис приёма отчётов автотестов (Go)внутренний 8080
webКабинет и обратный прокси Caddy с TLS80, 443

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

4.2. Требования и проверенные ОС

  • Сервер Linux x86-64, от 2 vCPU и 4 ГБ ОЗУ, от 20 ГБ диска; bash, openssl, curl, python3.
  • Docker Engine с Docker Compose (v2 или docker-compose 1.29) либо Podman с podman-compose — из штатного репозитория ОС.
  • Имя сервера для пользователей. TLS — собственный центр сертификации Коробки, Let's Encrypt или сертификат заказчика.

Установка и приёмочная проверка пройдены на чистых серверах с рантаймом из репозиториев самих ОС:

ОСРантайм контейнеров
Astra Linux Special Edition 1.7, уровень «Воронеж»Docker 25 и docker-compose 1.29
РЕД ОС 8.0, сертифицированная редакцияDocker 29 и Compose v2; Podman 6.1 и podman-compose
РЕД ОС 7.3, сертифицированная редакцияDocker 29 и Compose v2
Альт Сервер 11 и 10Docker 29 / 27 и Compose v2
Ubuntu 24.04Docker 29 и Compose v2

Приёмочная проверка входит в поставку: вход администратора, проект, кейсы, приём JUnit-отчёта и итог прогона. На Astra Linux проверка шла с включённым мандатным контролем целостности; замкнутая программная среда настраивается вместе с заказчиком. Сертификация QA Деск во ФСТЭК не проводилась.

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

  1. Распакуйте архив на сервере и сверьте контрольные суммы:
    tar -xzf qadesk-box-<версия>.tar.gz && cd qadesk-box
    sha256sum -c SHA256SUMS
  2. Запустите установщик — он проверит ОС и рантайм, сгенерирует ключи и пароли, загрузит образы, применит миграции базы, запустит службы и создаст администратора (пароль покажет один раз):
    sudo bash install.sh --domain qa.company.ru --admin-email admin@company.ru
  3. Проверьте экземпляр:
    cd /opt/qadesk-box && bash smoke.sh https://qa.company.ru --insecure
    Последняя строка — ПРИЁМКА КОРОБКИ: OK.
  4. Обновление — тот же install.sh из нового архива: данные и ключи сохраняются, миграции применяются автоматически.

В закрытом контуре без почтового сервиса пользователей заводит администратор: регистрация и приглашения по письму требуют подключения почты.

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). После проверки готовности откройте кабинет в браузере и выполните регистрацию первого пользователя.