Перейти к содержимому

Сервер

Мы предлагаем версию сервера Tuist для самостоятельного размещения в организациях, которым требуется больший контроль над своей инфраструктурой. Эта версия позволяет размещать Tuist на собственной инфраструктуре, обеспечивая безопасность и конфиденциальность ваших данных.

Требуется лицензия

Для самостоятельного размещения Tuist необходима юридически действительная платная лицензия. Версия Tuist для локального развертывания доступна только для организаций с тарифным планом Enterprise. Если вас интересует эта версия, свяжитесь с нами по адресу [email protected].

Устаревший сервис кэширования

Старая технология узлов кэша для самостоятельного размещения устарела для новых установок. Используйте руководство по самостоятельному размещению кэша для актуальной инфраструктуры кэша при самостоятельном размещении.

Существующие развертывания могут по-прежнему обращаться к устаревшей исходной документации в просмотрщике Markdown на GitHub: узлы кэша и архитектура кэша.

Частота выпусков#

Сервер Tuist и сервер кэша Kura поставляются через три канала образов GHCR: canary (каждый коммит в main), release candidate (формируется каждый понедельник, тестируется неделю) и stable (повышается до стабильного в следующий понедельник). Только стабильные релизы перемещают тег :latest и разрешаются по умолчанию; версии canary и release candidate являются предварительными релизами GitHub, которые вы выбираете, закрепляя их тег. Сервер и Kura следуют одному еженедельному циклу выпуска, синхронно с графиком выпусков CLI Tuist.

Мы следуем семантическому версионированию, чтобы обеспечить предсказуемость версий и совместимость. Старшая версия используется для обозначения критических изменений в сервере Tuist, которые потребуют координации с пользователями, самостоятельно размещающими сервер; вам не следует ожидать, что мы будем часто её использовать, а в случае необходимости будьте уверены, что мы поможем сделать переход максимально плавным.

На странице Каналы выпусков описано, как формируется каждый канал, как закрепить нужный канал в вашем развертывании и какая стратегия рекомендуется для поддержания производства на медленно обновляемой стабильной ветке, пока тестовое окружение проверяет предстоящий релиз.

Обновление браузерных сессий#

Браузерные сессии истекают через семь дней без аутентифицированных запросов страниц или взаимодействия с LiveView, но не позднее чем через 30 дней после аутентификации. Функция «Запомнить меня» восстанавливает ту же серверную сессию и не может продлить ни один из этих сроков. Активность фиксируется раз в минуту, поэтому неактивная сессия может истечь на 59 секунд раньше. Heartbeat-сигналы WebSocket, автоматические переподключения и фоновые обновления не возобновляют активность. Эти сроки не влияют на срок действия учетных данных машин или API-токенов.

Выполните аддитивную миграцию users_tokens перед запуском обновленных процессов приложения. Существующие строки не заполняются ретроспективно: время их создания ограничивает период неактивности и абсолютный срок действия, и перед доступом к организации с принудительным SSO необходимо пройти новую аутентификацию. Провайдер колбэка, эмитент или проверенное рабочее пространство, а также пользовательское подключение SSO хранятся на стороне сервера и сравниваются с текущими настройками организации. Связанный аккаунт не является доказательством аутентификации сессии.

Обновите каждую веб-реплику, обслуживающую трафик, прежде чем считать политику примененной. Старые бинарные файлы всё ещё могут принимать свои прежние 60-дневные сессии и не применяют новое ограничение LiveView; смешанные версии совместимы по схеме, но не эквивалентны по политике. Ожидайте, что пользователям потребуется войти снова. Откат к старым бинарным файлам ослабляет эти элементы управления; если необходим откат схемы, остановите все бинарные файлы, читающие новые поля, прежде чем удалять их. Никогда не продлевайте старые сессии и не пытайтесь обойти повторную аутентификацию.

MFA через приложение-аутентификатор#

Сервер включает встроенную двухфакторную аутентификацию через приложение-аутентификатор (TOTP). В панели управления пока нет ссылки на неё; точка входа в настройки будет добавлена в следующем релизе. Для работы не требуются флаг активации, зависимость от хостингового сервиса или учетные данные провайдера идентификации: нужны только PostgreSQL, миграция ниже, TOTP-аутентификатор и стабильный ключ шифрования, общий для всех обслуживающих реплик (TUIST_SECRET_KEY_ENCRYPTION, с откатом к TUIST_SECRET_KEY_BASE). Синхронизируйте часы сервера и аутентификатора. Проверка MFA и общий лимит из пяти неудачных попыток ввода кода за пять минут используют блокировки строк PostgreSQL, а не Redis.

Для настройки требуется вход в систему в течение последних пяти минут, ввод ключа настройки в приложение TOTP-аутентификатора и подтверждение сгенерированного приложением кода. Десять одноразовых кодов восстановления показываются один раз; сохраните их в безопасном месте. Отключение фактора также требует недавнего входа в систему и неиспользованного кода аутентификатора или кода восстановления. Изменение фактора аннулирует другие браузерные сессии. Сброс пароля не удаляет MFA, и эта реализация не предоставляет обходного пути только по электронной почте или через администратора при потере фактора.

После регистрации каждый новый вход через браузер, включая федеративный вход, требует использования встроенного второго фактора перед получением сессии или завершением авторизации CLI/устройства через браузер. Прямой вход по паролю и через Apple API отказывает зарегистрированным пользователям и предлагает использовать вход через браузер. Новые утверждения почтового агента для зарегистрированных пользователей требуют браузерной сессии, прошедшей проверку MFA; устаревшие утверждения только по почтовому ящику отклоняются. Существующие API-токены, учетные данные машин, идентификаторы рабочих нагрузок и правила их обновления остаются без изменений. Это необязательная поддержка для каждого пользователя, а не обязательное требование MFA для всей организации и не проверка политики MFA самого провайдера идентификации. Для SSO организации по-прежнему требуется правильный настроенный провайдер/эмитент в дополнение к встроенному фактору.

Электронная почта не требуется для регистрации, входа в систему, использования кодов восстановления или отключения MFA. Уведомления об изменении фактора отправляются по принципу best-effort; ошибка доставки не отменяет выполненное изменение.

Выполните отдельную аддитивную миграцию user_mfa/users_tokens.mfa_verified_at перед запуском нового бинарного файла. Секрет TOTP использует существующий ключ шифрования Vault; сохраните этот ключ и его резервные копии. Завершите обновление всех реплик, обслуживающих аутентификацию, прежде чем разрешать регистрацию MFA. Старые бинарные файлы могут обходить встроенную MFA, поэтому они не являются совместимыми с политикой целями для отката после регистрации. Удаление схемы MFA уничтожает состояние регистрации и восстановления; сначала остановите процессы чтения и сохраните зашифрованную резервную копию. Совместимость схем смешанных версий не является доказательством того, что применяются элементы управления MFA или браузерными сессиями.

Граница обновления и отката OAuth#

Удаление кэша сущностей OAuth требует поэтапного обновления для существующих установок. Перед развертыванием версии, которая прекращает инвалидацию кэша OAuth, сначала разверните релиз совместимости с авторитетным чтением из #14040 на каждый компонент чтения и записи OAuth. Этот этап совместимости впервые появляется в линии релизов 1.355: ghcr.io/tuist/tuist:1.355.0-rc.1 содержит его; для продакшн-развертываний следует использовать стабильный релиз 1.355.x после его продвижения. Установки версии 1.354 или более ранние должны завершить этот этап перед обновлением до более позднего релиза, содержащего удаление. Сохраняйте линию 1.355 только для совместимости: не портируйте обратно удаление инвалидации в нее.

Оригинальный коммит совместимости также доступен как ghcr.io/tuist/tuist:sha-c8e54471a425. Другой образ подходит в качестве этапа совместимости только если он сохраняет авторитетное чтение и сохраняет устаревшие инвалидации, пока существуют старые потребители. Выполните обычные миграции базы данных для этого этапа перед обработкой трафика, включая индекс поиска токенов обновления.

Проверьте все веб-реплики, фоновые воркеры, запланированные задачи и отдельно закрепленные образы процессоров в каждой среде. Дождитесь завершения rollout совместимости и убедитесь, что не осталось бинарных файлов, читающих кэш, прежде чем удалять инвалидации. Не допускайте, чтобы плавающий тег образа пропустил этот этап во время автоматического обновления. Свежие установки без старых потребителей не требуют промежуточного развертывания.

Сохраните цель отката с авторитетным чтением

После удаления инвалидаций обычный rolling rollback должен быть направлен на #14040 или другую версию с авторитетным чтением. Сохраненные записи кэша OAuth могут быть устаревшими даже после остановки всех процессов без инвалидации, и перезапущенная реплика, читающая кэш, может импортировать их от пиров.

Дальнейший откат требует остановки и дренажа всех потребителей OAuth без инвалидации, затем очистки или замены каждого сохраненного участника кэша Boruta перед запуском любого потребителя, читающего кэш. Предотвратите повторное подключение сохраненных участников. Дренаж только входящего трафика или перезапуск только веб-реплик недостаточны; согласуйте это восстановление с вашей контактной службой поддержки Tuist, а не очищайте кэши или автоматически откатывайте миграции базы данных.

Кластеризация нескольких реплик#

Поддерживаемые веб-развертывания с несколькими репликами требуют кластеризации Erlang для межрепликовых уведомлений Phoenix PubSub и Oban PG, а не в качестве органа аутентификации. Chart отвергает несколько реплик, включая автомасштабировщик, который может расти beyond одной реплики, когда server.cluster.enabled имеет значение false. Ранее принятые некластеризованные развертывания должны планировать это обновление, а не обходить защиту. Завершите последовательность обновления OAuth, включая удаление инвалидации, перед изменением членства.

Создайте приватный Secret cookie в namespace релиза, используя ваш менеджер секретов, затем настройте его имя и ключ:

yaml
server:
replicaCount: 2
cluster:
enabled: true
distributionPort: 9100
cookieExistingSecret: tuist-server-cluster
cookieExistingSecretKey: release-cookie

Cookie должен иметь высокую энтропию и использоваться всеми участвующими веб-репликами. Никогда не используйте cookie, встроенный в опубликованный образ: владение cookie распределения предоставляет удаленное выполнение на его узлах. Запуск распределенного релиза теперь отказывает при отсутствии приватного RELEASE_COOKIE или неверном порте, включая явно настроенные RELEASE_DISTRIBUTION=name или sname без обнаружения через DNS. Развертывания без chart также должны последовательно настроить TUIST_CLUSTER_DNS_SERVICE, TUIST_CLUSTER_APP_NAME и IP-адрес пода/имя узла. Обнаружение в настоящее время использует записи A IPv4.

При обычном helm upgrade, подключенном к серверу, оставление cookieExistingSecret пустым создает Secret cookie и повторно использует его текущее значение при последующих обновлениях. Оффлайн helm template, Argo CD и другие рендереры GitOps без живого поиска Secret не могут сохранить это сгенерированное значение; они должны использовать cookieExistingSecret, поддерживаемый отдельно управляемым, стабильным Secret. Не меняйте ключ cookie для неявной ротации работающего кластера. Ротация cookie требует скоординированной миграции/перезапуска каждого участника; обновление только Secret не обновляет существующие процессы.

Первый rollout из cookie, встроенных в образ, формирует отдельные острова членства старой/новой версии, пока все веб-реплики не начнут использовать приватный Secret. Запланируйте окно миграции для обновлений в реальном времени. Последующие rolling deployments формируют кластеры смешанных версий, поэтому учитывайте PubSub, уведомления Oban и замену пиров across фактических старых/новых версий. Эти уведомления не являются гарантиями надежной доставки. Сохраняйте образ отката с авторитетным чтением и сохраняйте тот же приватный cookie при откате совместимой версии.

Разрешите EPMD (TCP 4369) и настроенный порт распределения только между доверенными пирами сервера, никогда от рабочих нагрузок арендаторов или публичной сети. Проверьте фактическую изоляцию ingress/egress в вашей среде; применение NetworkPolicy не доказывает enforcement или доступность бэкенда. Canary с двумя репликами под непрерывной нагрузкой должен пройти присоединение, rolling replacement и восстановление после сбоя перед продвижением. DNS используется для обнаружения пиров, а не для отключения здоровых узлов при временном сбое или частичном ответе; реальная потеря узлов и предотвращение разделения OTP все еще применяются. libcluster может все еще регистрировать успешную операцию "отключено" для callback сохранения без закрытия соединения; устанавливайте фактическое членство по событиям node-up/down или Node.list(), а не только по этой строке лога.

Непрерывное развертывание#

Мы рекомендуем закреплять production-окружение на стабильной минорной ветке (например, ghcr.io/tuist/tuist:1.351), чтобы ежедневные обновления доставляли только исправления, портированные из новых версий. Стабильные ветки публикуются каждый понедельник в 06:00 UTC после недельного тестирования в канале release-candidate; staging-окружение на canary или на текущем теге release-candidate позволит выявить регрессии до того, как они достигнут ваших пользователей. См. Каналы релизов для получения рекомендаций по стратегии закрепления версий.

Если вы предпочитаете получать новые возможности по мере их стабилизации без изменения манифестов, закрепите тег :latest. Тег обновляется раз в неделю утром в понедельник, поэтому планируйте окно развертывания соответствующим образом. Ниже приведен пример рабочего процесса GitHub Actions, который проверяет наличие и развертывает последний стабильный образ с такой периодичностью:

yaml
name: Update Tuist Server
on:
schedule:
- cron: '0 8 * * 1' # Mondays 08:00 UTC, after the weekly stable promote
workflow_dispatch: # Allow manual runs
jobs:
update:
runs-on: ubuntu-latest
steps:
- name: Check and deploy latest version
run: |
# Your deployment commands here
# Example: docker pull ghcr.io/tuist/tuist:latest
# Deploy to your infrastructure

Доступ из доверенной сети#

Установки с самостоятельным хостингом могут разрешать разработчикам в доверенной сети отправлять аналитику, использовать кэш или делать и то, и другое без входа в систему. Панель управления и администрирование по-прежнему требуют аутентификации.

Включайте только те возможности, которые вам нужны:

Переменная окружения сервера Разрешено без входа в систему
TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS=true Отправка аналитики сборок и тестов
TUIST_NETWORK_TRUSTED_CACHE_ACCESS=true Чтение и запись кэшированных результатов сборки

Обе настройки по умолчанию отключены, независимы и применяются ко всему экземпляру для всех аккаунтов и проектов, включая приватные проекты. Они недоступны в hosted Tuist и не заменяют лицензию на самостоятельный хостинг.

Предыдущее имя TUIST_NETWORK_TRUSTED_REPORT_PUBLISHING остается резервным вариантом для обратной совместимости, если TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS не задана.

Warning

Включайте эти настройки только за границей корпоративной сети или VPN с принудительным контролем доступа. Любой, кто может достичь включенной конечной точки, может отправлять отчеты или, при включенном доступе к кэшу, читать и перезаписывать кэшированные выходные данные. Это допускает подделку телеметрии, отравление кэша и исчерпание ресурсов. Ответы на отчеты также могут раскрывать идентификаторы приватных проектов и системы сборки. Tuist не проверяет членство в VPN и не доверяет перенаправляемым IP-заголовкам как доказательству членства.

Настройка экземпляра#

  1. Ограничьте доступ к серверу Tuist, каждому слушателю Kura HTTP/gRPC и любому входящему трафику Bazel BES вашей доверенной сетью, используя межсетевой экран или частный ingress.
  2. Обновите каждую реплику сервера и Kura перед обновлением клиентов. Оставьте аутентификацию Kura включенной с помощью KURA_AUTH_TUIST_URL и ее учетных данных плоскости управления; отключение обходит эти ограничения. Настройте конечную точку кэша, используя руководство по кэшу для самостоятельного хостинга.
  3. Установите желаемые переменные выше на каждой соответствующей реплике сервера Tuist, затем перезапустите или повторно разверните их. Только точное значение true включает настройку. В панели управления нет переключателя или отдельного флага Kura.

Настройка клиентов#

Настройте окончательный URL-адрес сервера с самостоятельным хостингом и проект на каждом совместимом клиенте. Клиенты автоматически определяют, какие возможности включены, когда учетные данные отсутствуют; участие клиента не требуется. Обнаружение не следует за перенаправлениями. Существующие учетные данные остаются в использовании, а недействительные или не обновленные учетные данные вызывают ошибку, а не анонимный откат. Войдите снова или явно выйдите, чтобы восстановить работу.

Перед включением доступа к аналитике обновите все инструменты, использующие общие учетные данные, до версий, которые сохраняют поврежденные или отклоненные учетные данные, отвергают нечитаемые каталоги учетных данных и исключают источники Git из неподписанных отчетов. Старые инструменты могут удалять учетные данные и непреднамеренно разрешать анонимный откат; обновление только сервера не может это исправить. Если сервер не поддерживает обнаружение или откатывается к более старой версии, клиенты должны проходить аутентификацию. Предыдущая настройка клиента TUIST_NETWORK_TRUSTED_PUBLISHING больше не применяется.

  • Аналитика: Отправляйте только завершенные отчеты Xcode, Gradle, Elixir/Mix и Bazel, без доступа к архивам, вложениям, покрытию кода, планированию шардов или существующим отчетам. Заявления об акторе не проверяются; неподписанная телеметрия не формирует доверенные доказательства тестов или автоматизацию. См. руководства по Xcode, Gradle и Elixir для настройки клиента и деталей конфиденциальности.
  • Кэш: Поддерживается кэширование компиляции/модулей через CLI, кэширование Bazel и кэширование задач Gradle. Очистка кэша и загрузка Remote Asset по-прежнему требуют учетных данных. Клиенты без поддержки должны продолжать аутентификацию.
  • Bazel: Для отчетности требуется явное указание TUIST_BAZEL_BES_BACKEND и совместимая Kura. Параметры кэша и отчетности включаются независимо. Повторно запустите tuist bazel setup после изменения учетных данных или любой из настроек; повторно запустите tuist cache config для изменений конфигурации кэша компиляции.

Запросы на отправку отчетов ограничены 8 МБ, 60 запросами в минуту и 10 000 в день на проект. Настройте общий Valkey для квот на все развертывание с несколькими репликами; в противном случае лимиты применяются на процесс. Если настроенный общий бэкенд квот недоступен, неподписанная отчетность отклоняется. Добавьте также ограничения на входящие соединения, размер тела запроса и скорость.

Отключение доступа из доверенной сети#

Установите соответствующую переменную в false, затем перезапустите каждую соответствующую реплику сервера. Старые реплики могут продолжать принимать запросы без учетных данных до их замены. Доступ к кэшу для новых запросов прекращается в течение 60 секунд после переключения последней реплики; текущие передачи не отменяются. Блокируйте трафик на ingress сначала, если требуется немедленное отзывание прав. Существующие отчеты сохраняют свою обычную видимость и срок хранения, а аутентифицированные клиенты продолжают работать.

Требования к среде выполнения#

В этом разделе описаны требования для размещения сервера Tuist на вашей инфраструктуре.

Матрица совместимости#

Сервер Tuist был протестирован и совместим со следующими минимальными версиями:

Компонент Минимальная версия Примечания
PostgreSQL 15
ClickHouse 25 Требуется для аналитики

Запуск образов в виртуализации Docker#

Мы распространяем сервер как образ Docker через Container Registry GitHub.

Для его запуска ваша инфраструктура должна поддерживать запуск образов Docker. Обратите внимание, что большинство провайдеров инфраструктуры поддерживают это, так как это стало стандартным контейнером для распространения и запуска программного обеспечения в производственных средах.

База данных Postgres#

Помимо запуска образов Docker, вам понадобится база данных Postgres для хранения реляционных данных. Большинство провайдеров инфраструктуры включают базы данных Postgres в свои предложения (например, AWS и Google Cloud).

Миграции

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

База данных ClickHouse#

Tuist использует ClickHouse для хранения и запроса больших объемов аналитических данных. ClickHouse обязателен для таких возможностей, как аналитика сборок. Вы можете выбрать самостоятельное размещение ClickHouse или использовать их управляемый сервис.

Миграции

Точка входа образа Docker автоматически выполняет все ожидающие миграции схемы ClickHouse перед запуском сервиса.

Встроенные конфигурации ClickHouse для Docker Compose и Helm снижают уровень текстового журнала ClickHouse со значения по умолчанию trace до information, что является основным источником объема system.text_log. Обе конфигурации также могут ограничивать собственные таблицы оперативных журналов system.* в ClickHouse, которые иначе не имеют ограничений, но по умолчанию эта функция отключена — см. ниже. Во внешних развертываниях ClickHouse следует настраивать эти оперативные журналы непосредственно в сервисе ClickHouse.

Топология репликации ClickHouse#

Многорежимная репликация ClickHouse за Tuist поддерживается только в ClickHouse Cloud. Самостоятельно управляемый ClickHouse работает с одной репликой.

Миграции приема данных создают движок MergeTree. В облаке он прозрачно превращается в SharedMergeTree, поэтому запись идет в общее объектное хранилище, и любое количество реплик работает корректно. В самостоятельно управляемом ClickHouse MergeTree пишет на локальный диск только одной реплики; многорепличная настройка либо тихо разделит прием данных между репликами, либо отклонит создание с ошибкой UNKNOWN_STORAGE: Only tables with a Replicated engine or tables which do not store data on disk are allowed in a Replicated database. в зависимости от того, как параметр database_replicated_allow_only_replicated_engine настроен у подключающегося пользователя.

Запускайте один шард с одной репликой в самостоятельно управляемом ClickHouse и регулярно создавайте резервные копии каталога данных ClickHouse. Если узел будет потерян, второй реплики для восстановления не будет.

Ограничение срока хранения оперативных журналов#

Срок хранения можно применить к system.text_log, system.query_log, system.query_thread_log, system.query_views_log, system.trace_log, system.metric_log, system.asynchronous_metric_log и system.part_log.

Включение этой функции — одноразовое необратимое действие для экземпляра, в котором уже есть данные, поэтому ни один из пакетов не делает этого за вас. Любое окно хранения приводит к тому, что определения таблиц перестают соответствовать их конфигурации, поэтому ClickHouse переименовывает каждую из них и создает новую таблицу, как описано в разделе замещенные таблицы журналов. Оставленная версия хранит все накопленные на данный момент данные и не имеет собственного срока хранения, поэтому, если вы не освободите место на этом же шаге, она останется на диске навсегда, а новое окно будет ограничивать только строки, записанные с этого момента. Включите обе настройки вместе:

yaml
clickhouse:
embedded:
systemLogs:
ttlDays: 14
supersededTables: delete

Эта единственная операция helm upgrade самодостаточна, потому что изменение ttlDays с пустого значения на заданное добавляет монтирование и перезапускает под ClickHouse: он перезагружается, замещает таблицы, а задача после обновления затем удаляет их. Развертывайте с помощью helm upgrade --wait, чтобы под был перезапущен до запуска задачи; в противном случае версии появятся после того, как задача уже проверила состояние, и следующее выполнение helm upgrade освободит место вместо нее.

В Docker Compose раскомментируйте том clickhouse-log-ttl.xml для сервиса clickhouse в файле docker-compose.yml и установите обе переменные в .env:

bash
CLICKHOUSE_SYSTEM_LOG_TTL_DAYS=14
CLICKHOUSE_SUPERSEDED_LOG_TABLES=delete

После освобождения места вы можете вернуть supersededTables/CLICKHOUSE_SUPERSEDED_LOG_TABLES к значению ignore, чтобы последующее обновление ClickHouse не удаляло историю самостоятельно.

Замещенные таблицы журналов#

При запуске ClickHouse проверяет, соответствует ли каждая системная таблица журнала своей конфигурации. Если нет, он переименовывает существующую таблицу в system.<name>_0, затем в _1, _2 и так далее, и создает новую. Это происходит при изменении окна хранения и при любом обновлении ClickHouse, которое меняет схему системного журнала.

Переименование таблицы не копирует ее данные, поэтому дополнительное место на диске не тратится. Что происходит с замещенной таблицей afterward, зависит от исходной таблицы, так как она сохраняет тот срок хранения, который был у активной таблицы в момент замещения. При первом включении хранения у замещаемой таблицы срока нет, поэтому она хранит всю накопленную историю бессрочно. Последующее изменение окна замещает таблицу, которая уже имеет TTL, поэтому такие данные истекают сами, оставляя пустую таблицу. ClickHouse никогда не удаляет сами таблицы, поэтому на долгоживущем экземпляре они накапливаются в любом случае.

Замещенные таблицы сохраняются по умолчанию, чтобы обновление никогда не удаляло оперативную историю самостоятельно. Установите политику в delete, чтобы удалять их, что происходит при docker compose up и каждом helm upgrade:

bash
CLICKHOUSE_SUPERSEDED_LOG_TABLES=delete

В диаграмме Helm настройте ту же политику как значение:

yaml
clickhouse:
embedded:
systemLogs:
supersededTables: delete

Удаление замещенной таблицы освобождает занимаемое ею место на диске. Активная таблица никогда не затрагивается, как и строки, записанные после ее замещения.

Чтобы освободить место один раз без изменения политики, удалите таблицы вручную:

sql
SELECT name FROM system.tables WHERE database = 'system' AND match(name, '_log_[0-9]+$');
DROP TABLE IF EXISTS system.text_log_0 SYNC;

База данных system использует движок Atomic, который откладывает обычное DROP TABLE на database_atomic_delay_before_drop_table_sec (по умолчанию восемь минут). SYNC удаляет данные немедленно, что нужно при удалении этих таблиц из-за заполнения диска.

Хранилище#

Вам также понадобится решение для хранения файлов (например, бинарных файлов фреймворков и библиотек). Сервер Tuist поддерживает S3-совместимые хранилища и Azure Blob Storage для артефактов, принадлежащих серверу.

Оптимизированное кэширование

Если ваша главная цель — снизить задержку кэша, вам, возможно, не нужно самостоятельно размещать весь сервер. Вы можете развернуть узлы Kura рядом с вашей CI-средой или сетью разработчиков и подключить их к управляемому серверу Tuist или вашему самостоятельно размещенному серверу.

См. руководство по самостоятельному размещению кэша.

Самостоятельно размещенные узлы Kura#

Чтобы использовать самостоятельно размещенные узлы Kura с самостоятельно размещенным сервером Tuist:

  1. Настройте KURA_CONTROL_PLANE_CLIENT_ID и KURA_CONTROL_PLANE_CLIENT_SECRET на сервере Tuist. Идентификатор клиента должен быть UUID. Сгенерируйте UUID и случайный секрет с помощью команд из руководства по самостоятельному размещению кэша и сохраните их в секретах вашего развертывания.
  2. Разверните узлы Kura, следуя руководству по самостоятельному размещению кэша, используя те же учетные данные плоскости управления.
  3. Настройте каждый узел Kura с помощью KURA_REGISTRATION_URL и KURA_ADVERTISED_HTTP_URL. Heartbeat-сигналы регистрации сообщают серверу, какие готовые конечные точки Kura, обращенные к клиенту, он может рекламировать CLI.

Конфигурация#

Конфигурация сервиса выполняется во время выполнения через переменные окружения. Учитывая чувствительный характер этих переменных, мы рекомендуем шифровать их и хранить в надежных решениях для управления паролями. Будьте уверены, Tuist обращается с этими переменными с особой осторожностью, гарантируя, что они никогда не отображаются в логах.

Проверки при запуске

Необходимые переменные проверяются при запуске. Если какие-либо из них отсутствуют, запуск завершится ошибкой, а сообщение об ошибке укажет на отсутствующие переменные.

Конфигурация лицензии#

Как пользователь on-premise решения, вы получите лицензию, которую нужно будет указать в виде переменной окружения. Лицензия используется для проверки развертывания и обеспечения того, что сервис работает в соответствии с условиями соглашения.

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_LICENSE Лицензия, предоставляемая после подписания соглашения об уровне обслуживания. Принимает либо стандартный ключ лицензии, либо сертификат в кодировке base64, используемый в изолированных средах, где сервер не может обращаться к внешним службам. Да ******
Срок действия

У лицензий есть срок действия. Пользователи получат предупреждение при использовании команд Tuist, взаимодействующих с сервером, если срок действия лицензии истекает менее чем через 30 дней. Если вы хотите продлить лицензию, пожалуйста, свяжитесь с [email protected].

Базовая конфигурация окружения#

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_APP_URL Базовый URL для доступа к экземпляру из Интернета Да https://tuist.dev
TUIST_SECRET_KEY_BASE Ключ, используемый для шифрования информации (например, сессий в cookie) Да c5786d9f869239cbddeca645575349a570ffebb332b64400c37256e1c9cb7ec831345d03dc0188edd129d09580d8cbf3ceaf17768e2048c037d9c31da5dcacfa
TUIST_SECRET_KEY_PASSWORD Дополнительный секрет (pepper) для генерации хешированных паролей Нет $TUIST_SECRET_KEY_BASE
TUIST_SECRET_KEY_TOKENS Секретный ключ для генерации случайных токенов Нет $TUIST_SECRET_KEY_BASE
TUIST_SECRET_KEY_ENCRYPTION 32-байтовый ключ для AES-GCM шифрования конфиденциальных данных Нет $TUIST_SECRET_KEY_BASE
TUIST_USE_IPV6 При значении 1 приложение настраивается на использование адресов IPv6 Нет 0 1
TUIST_LOG_LEVEL Уровень логирования для приложения Нет info Уровни логирования
TUIST_GITHUB_APP_NAME Слаг вашего GitHub-приложения, взятый из https://github.com/apps/<slug>. Требуется для установки приложения. См. GitHub Нет my-app
TUIST_GITHUB_APP_PRIVATE_KEY_BASE64 Закрытый ключ в кодировке base64, используемый GitHub-приложением для разблокировки дополнительных функций, таких как автоматическое добавление комментариев к PR Нет LS0tLS1CRUdJTiBSU0EgUFJJVkFUR...
TUIST_GITHUB_APP_PRIVATE_KEY Закрытый ключ, используемый GitHub-приложением для разблокировки дополнительных функций, таких как автоматическое добавление комментариев к PR. Рекомендуем использовать версию в кодировке base64, чтобы избежать проблем со специальными символами Нет -----BEGIN RSA...
TUIST_OPERATOR_EMAIL_DOMAIN Пользователи, чей адрес электронной почты заканчивается на @<this-domain> и которые подтвердили контроль над ним, могут получать доступ к URL-адресам операций (/ops/*). Если переменная не задана, доступ к ним закрыт для всех. См. Операции Нет example.com
TUIST_SERVER_VERSION_IDENTIFIER Метка, отображаемая в виде значка в навигационной панели дашборда для идентификации экземпляра сервера (например, номер версии или имя ветки) Нет Ветка Git в среде разработки v1.2.3
TUIST_WEB Включить конечную точку веб-сервера Нет 1 1 или 0
TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS Разрешить отправку аналитики сборок и тестов без входа в систему. См. Доступ по доверию сети для настройки и требований безопасности. Нет false true
TUIST_NETWORK_TRUSTED_CACHE_ACCESS Разрешить чтение и запись в кэш без входа в систему. См. Доступ по доверию сети для настройки и требований безопасности. Нет false true
TUIST_OTEL_EXPORTER_OTLP_ENDPOINT gRPC-конечная точка OpenTelemetry Collector для отправки трассировок Нет http://localhost:4317
TUIST_LOKI_URL Базовый URL совместимой с Loki конечной точки для отправки логов (например, Grafana Alloy или Loki) Нет http://localhost:3100
Обслуживайте приложение через HTTPS

Куки сессии помечены как Secure, поэтому браузеры игнорируют их при обычном http://, и пользователи не могут войти в систему. Завершайте TLS перед сервером (достаточно обратного прокси с сертификатом от вашего внутреннего CA) и установите TUIST_APP_URL на URL с https://, даже для внутренних развертываний или развертываний только через VPN.

Конфигурация базы данных#

Следующие переменные окружения используются для настройки подключения к базе данных:

Переменная окружения Описание Обязательно По умолчанию Пример
DATABASE_URL URL для доступа к базе данных Postgres. Обратите внимание, что URL должен содержать информацию для аутентификации Да postgres://username:[email protected]/production
TUIST_DATABASE_SCHEMA Схема PostgreSQL, используемая таблицами приложения Tuist. Установите это значение, если политика вашей базы данных запрещает использование схемы public. Имя схемы должно быть идентификатором PostgreSQL без кавычек. Нет public tuist
TUIST_MIGRATION_DATABASE_URL Необязательный URL Postgres, используемый только Tuist.Release.migrate. Установите его как URL роли владельца, когда DATABASE_URL указывает на роль с более узкими правами времени выполнения. Нет DATABASE_URL postgres://owner:[email protected]/production
TUIST_DATABASE_RUNTIME_ROLE Роль Postgres времени выполнения, которой миграции должны предоставлять привилегии на таблицы приложения после завершения. Используйте это вместе с TUIST_MIGRATION_DATABASE_URL, если веб-сервер не должен подключаться как владелец схемы. Нет tuist_web
TUIST_CLICKHOUSE_URL URL для доступа к базе данных ClickHouse. Обратите внимание, что URL должен содержать информацию для аутентификации Нет http://username:[email protected]/production
TUIST_USE_SSL_FOR_DATABASE Если true, используется SSL для подключения к базе данных. Сертификат сервера не проверяется, если не включен TUIST_DATABASE_SSL_VERIFY Нет 1 1
TUIST_DATABASE_SSL_VERIFY Если true, сертификат сервера базы данных должен иметь цепочку доверия к надежному CA и совпадать с хостом в DATABASE_URL. Требуется TUIST_USE_SSL_FOR_DATABASE. Рекомендуем включить эту опцию. Нет 0 1
TUIST_DATABASE_SSL_CA_CERT_FILE Путь к PEM-файлу с сертификатами CA, используемыми для проверки сервера базы данных. Если не задан, используется хранилище доверия операционной системы. Нет /etc/tuist/rds-global-bundle.pem
TUIST_DATABASE_POOL_SIZE Количество соединений, поддерживаемых открытыми в пуле подключений Нет 10 10
TUIST_DATABASE_QUEUE_TARGET Интервал (в миллисекундах) для проверки того, заняты ли все подключения из пула дольше интервала очереди (Подробнее) Нет 300 300
TUIST_DATABASE_QUEUE_INTERVAL Пороговое время (в миллисекундах) ожидания в очереди, по которому пул определяет, следует ли начинать отбрасывать новые подключения (Подробнее) Нет 1000 1000
TUIST_CLICKHOUSE_FLUSH_INTERVAL_MS Временной интервал в миллисекундах между сбросами буфера ClickHouse Нет 5000 5000
TUIST_CLICKHOUSE_MAX_BUFFER_SIZE Максимальный размер буфера ClickHouse в байтах перед принудительным сбросом Нет 1000000 1000000
TUIST_CLICKHOUSE_BUFFER_POOL_SIZE Количество процессов буфера ClickHouse для запуска Нет 5 5

По умолчанию Tuist шифрует подключение к базе данных, но не проверяет сертификат сервера, поэтому злоумышленник в сетевом пути может выдать себя за базу данных. Установите TUIST_DATABASE_SSL_VERIFY=1, чтобы включить проверку. Если ваш провайдер подписывает сертификаты собственным CA, как это делают Amazon RDS и Google Cloud SQL, скачайте его пакет CA, смонтируйте его в контейнере и укажите на него через TUIST_DATABASE_SSL_CA_CERT_FILE. Хост в DATABASE_URL должен совпадать с именем или IP-адресом в сертификате. При включенной проверке сертификат, не прошедший эти проверки, приведет к сбою каждого подключения к базе данных, поэтому после включения проверьте журналы сервера на наличие Bad Certificate или Unknown CA.

Когда TUIST_DATABASE_SCHEMA не равно public, миграции релиза создают схему, если она еще не существует, перед запуском цепочки миграций Ecto. Если роль миграции не может создавать схемы, создайте схему заранее и сделайте роль миграции ее владельцем.

Tuist направляет подключение к пользовательской схеме, устанавливая параметр сеанса search_path. Некоторые конфигурации Postgres с пулингом или проксированием (например, PgBouncer или управляемые базы данных, ограничивающие параметры запуска) не применяют это, и сеанс возвращается к public, что проявляется во время миграций как permission denied for schema public. При подключении через такую конфигурацию закрепите схему за самой ролью, чтобы каждый сеанс начинался в ней независимо от прокси:

sql
CREATE SCHEMA IF NOT EXISTS tuist AUTHORIZATION <migration_role>;
ALTER ROLE <migration_role> IN DATABASE <database> SET search_path = tuist;
-- If the web server connects as a separate runtime role (TUIST_DATABASE_RUNTIME_ROLE):
ALTER ROLE <runtime_role> IN DATABASE <database> SET search_path = tuist;

Конфигурация окружения аутентификации#

Мы обеспечиваем аутентификацию через провайдеров удостоверений (IdP). Чтобы использовать эту возможность, убедитесь, что все необходимые переменные окружения для выбранного провайдера присутствуют в окружении сервера. Отсутствие переменных приведет к тому, что Tuist пропустит этого провайдера.

Электронная почта и пароль#

Вход по электронной почте и паролю и самостоятельная регистрация встроены и включены по умолчанию. В экземпляре, где требуется использовать провайдер удостоверений (например, при принудительном использовании SSO), вы можете полностью отключить их. Это удалит форму входа по электронной почте/паролю, ссылку на регистрацию и процесс сброса пароля из процесса входа, а также закроет все соответствующие серверные конечные точки, включая конечную точку электронной почты/пароля, используемую CLI (tuist auth).

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_EMAIL_AUTH_ENABLED Можно ли использовать электронную почту и пароль для входа и регистрации. Установите значение 0, чтобы удалить форму входа по электронной почте/паролю, ссылку на регистрацию и процесс сброса пароля со страницы входа и закрыть соответствующие серверные конечные точки Нет 1 0

Отключение настроенного провайдера удостоверений#

По умолчанию провайдер появляется как вариант входа, когда он настроен. Чтобы оставить провайдер настроенным (его учетные данные остаются установленными), но убрать его со страниц входа и регистрации, установите соответствующий переключатель в 0. Для GitHub, Google и Apple это также закрывает обратный вызов входа, поэтому метод становится полностью недоступным.

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_GITHUB_AUTH_ENABLED Можно ли использовать GitHub для входа (см. раздел GitHub, чтобы узнать, почему приложение использует свои учетные данные для входа) Нет 1 0
TUIST_GOOGLE_AUTH_ENABLED Можно ли использовать Google для входа Нет 1 0
TUIST_OKTA_AUTH_ENABLED Можно ли использовать настроенный провайдер Okta как вариант входа Нет 1 0
TUIST_APPLE_AUTH_ENABLED Можно ли использовать Apple для входа Нет 1 0

GitHub#

Мы рекомендуем выполнять аутентификацию с помощью приложения GitHub, но вы также можете использовать приложение OAuth. Обязательно добавьте все необходимые переменные окружения, указанные GitHub, в окружение сервера. Отсутствие переменных приведет к тому, что Tuist проигнорирует аутентификацию через GitHub. Чтобы правильно настроить приложение GitHub:

  • В общих настройках приложения GitHub:
    • Скопируйте Client ID и установите его как TUIST_GITHUB_APP_CLIENT_ID
    • Создайте и скопируйте новый client secret, затем установите его как TUIST_GITHUB_APP_CLIENT_SECRET
    • Установите Callback URL как http://YOUR_APP_URL/users/auth/github/callback. В качестве YOUR_APP_URL можно также указать IP-адрес вашего сервера.
  • Требуются следующие разрешения:
    • Репозитории:
      • Pull-запросы: чтение и запись
    • Аккаунты:
      • Адреса электронной почты: только чтение

В разделе Account permissions настроек Permissions and events установите разрешение Email addresses на значение Read-only.

Затем вам нужно будет задать следующие переменные окружения в среде, где работает сервер Tuist:

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_GITHUB_APP_CLIENT_ID Идентификатор клиента приложения GitHub Да Iv1.a629723000043722
TUIST_GITHUB_APP_CLIENT_SECRET Секрет клиента приложения Да 232f972951033b89799b0fd24566a04d83f44ccc
TUIST_GITHUB_AUTH_ENABLED Можно ли использовать GitHub для входа. Приложение GitHub, которое вы настраиваете для интеграций с платформой (комментарии к PR и т. д.), использует те же клиентские учетные данные для входа, поэтому оно иначе отображается как вариант входа. Установите значение 0, чтобы сохранить приложение, но убрать GitHub со страницы входа Нет 1 0

Google#

Вы можете настроить аутентификацию через Google, используя OAuth 2. Для этого вам нужно создать новые учетные данные типа «Идентификатор клиента OAuth». При создании учетных данных выберите тип приложения «Веб-приложение», назовите его Tuist и задайте URI перенаправления как {base_url}/users/auth/google/callback, где base_url — это URL, по которому работает ваш размещенный сервис. После создания приложения скопируйте идентификатор клиента и секрет и установите их как переменные окружения GOOGLE_CLIENT_ID и GOOGLE_CLIENT_SECRET соответственно.

Области доступа экрана согласия

Возможно, вам потребуется создать экран согласия. При этом обязательно добавьте области доступа userinfo.email и openid и отметьте приложение как внутреннее.

Okta#

Вы можете включить аутентификацию через Okta с помощью протокола OAuth 2.0. Вам нужно будет создать приложение в Okta, следуя этим инструкциям.

После получения идентификатора клиента и секрета при настройке приложения Okta вам нужно будет задать следующие переменные окружения:

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_OKTA_1_CLIENT_ID Идентификатор клиента для аутентификации в Okta. Число должно быть идентификатором вашей организации Да
TUIST_OKTA_1_CLIENT_SECRET Секрет клиента для аутентификации в Okta Да

Число 1 нужно заменить на идентификатор вашей организации. Обычно это 1, но проверьте в своей базе данных.

Настройка хранилища#

Tuist требуется хранилище для артефактов, загружаемых через API. Для эффективной работы Tuist необходимо настроить одно из поддерживаемых решений для хранения.

Задайте TUIST_OBJECT_STORAGE_PROVIDER, чтобы выбрать бэкенд для хранения артефактов сервера:

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_OBJECT_STORAGE_PROVIDER Бэкенд для хранения артефактов сервера. Используйте s3 для S3-совместимого хранилища или azure_blob для Azure Blob Storage Нет s3 azure_blob

S3-совместимые хранилища#

Вы можете использовать любого S3-совместимого провайдера хранилища для хранения артефактов. Для аутентификации и настройки интеграции с провайдером хранилища требуются следующие переменные окружения:

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_S3_ACCESS_KEY_ID или AWS_ACCESS_KEY_ID Идентификатор ключа доступа для аутентификации у провайдера хранилища Да AKIAIOSFOD
TUIST_S3_SECRET_ACCESS_KEY или AWS_SECRET_ACCESS_KEY Секретный ключ доступа для аутентификации у провайдера хранилища Да wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
TUIST_S3_REGION или AWS_REGION Регион, в котором находится бакет Нет auto us-west-2
TUIST_S3_ENDPOINT или AWS_ENDPOINT Эндпоинт провайдера хранилища Да https://s3.us-west-2.amazonaws.com
TUIST_S3_BUCKET_NAME Имя бакета, в котором будут храниться артефакты Да tuist-artifacts
TUIST_S3_CA_CERT_PEM CA-сертификат в кодировке PEM для проверки HTTPS-соединений с S3. Полезно для изолированных сред с самоподписанными сертификатами или внутренними центрами сертификации. Нет Системный набор CA-сертификатов -----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----
TUIST_S3_CONNECT_TIMEOUT Тайм-аут (в миллисекундах) на установление соединения с провайдером хранилища Нет 3000 3000
TUIST_S3_RECEIVE_TIMEOUT Тайм-аут (в миллисекундах) на получение данных от провайдера хранилища Нет 5000 5000
TUIST_S3_POOL_TIMEOUT Тайм-аут (в миллисекундах) для пула соединений с провайдером хранилища. Используйте infinity, чтобы отключить тайм-аут Нет 5000 5000
TUIST_S3_POOL_MAX_IDLE_TIME Максимальное время простоя (в миллисекундах) для соединений в пуле. Используйте infinity, чтобы держать соединения открытыми неограниченно долго Нет infinity 60000
TUIST_S3_POOL_SIZE Максимальное количество соединений на один пул Нет 500 500
TUIST_S3_POOL_COUNT Количество используемых пулов соединений Нет Количество системных планировщиков 4
TUIST_S3_PROTOCOL Протокол, используемый при подключении к провайдеру хранилища (http1 или http2) Нет http1 http1
TUIST_S3_VIRTUAL_HOST Нужно ли формировать URL с именем бакета в качестве поддомена (виртуальный хост) Нет false 1
Аутентификация через веб-идентификатор AWS с использованием переменных окружения

Если ваш провайдер хранилища — AWS и вы хотите аутентифицироваться с помощью веб-токена идентичности, установите переменную окружения TUIST_S3_AUTHENTICATION_METHOD в значение aws_web_identity_token_from_env_vars, и Tuist будет использовать этот метод с обычными переменными окружения AWS.

Google Cloud Storage#

Для Google Cloud Storage следуйте этой документации, чтобы получить пару AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY. Значение AWS_ENDPOINT должно быть установлено в https://storage.googleapis.com. Остальные переменные окружения такие же, как для любого другого S3-совместимого хранилища.

Azure Blob Storage#

Для Azure Blob Storage задайте TUIST_OBJECT_STORAGE_PROVIDER=azure_blob и настройте учетные данные учетной записи Azure Storage:

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_AZURE_STORAGE_ACCOUNT_NAME Имя учетной записи Azure Storage Да tuiststorage
TUIST_AZURE_STORAGE_ACCOUNT_KEY Ключ доступа к учетной записи хранения, используемый для подписи REST-запросов Azure Blob и URL-адресов SAS Да ******
TUIST_AZURE_BLOB_CONTAINER_NAME Контейнер, в котором хранятся артефакты сервера Да tuist-artifacts
TUIST_AZURE_BLOB_ENDPOINT Эндпоинт службы Blob. Не указывайте, чтобы использовать https://<account>.blob.core.windows.net Нет Формируется из имени учетной записи https://tuiststorage.blob.core.windows.net
TUIST_AZURE_BLOB_SERVICE_VERSION Версия REST API Azure Blob, используемая для подписанных запросов и URL-адресов SAS Нет 2020-12-06 2020-12-06

При использовании Helm-чарта задайте server.storage.provider=azure_blob и заполните server.azureBlob.*. Настройки верхнего уровня objectStorage чарта остаются S3-совместимыми, поскольку опциональные рабочие нагрузки кэша и зеркала реестра по-прежнему ожидают S3-совместимое хранилище. Если эти рабочие нагрузки отключены и сервер использует Azure Blob, задайте objectStorage.mode=external и оставьте пустыми эндпоинт и учетные данные внешнего объектного хранилища, чтобы избежать развертывания встроенного сервиса MinIO.

Хранение артефактов#

Очистка артефактов по умолчанию отключена на самостоятельно размещаемых экземплярах. Для каждого поддерживаемого типа артефактов предусмотрена своя переменная окружения. Установите значение переменной в положительное целое число дней, чтобы включить очистку для этого типа артефактов. Если переменная не задана или оставлена пустой, очистка отключается только для соответствующего типа артефактов.

bash
TUIST_CACHE_ARTIFACT_RETENTION_DAYS=30
TUIST_APP_PREVIEW_RETENTION_DAYS=30
TUIST_BUILD_ARCHIVE_RETENTION_DAYS=60
TUIST_RUN_ARTIFACT_RETENTION_DAYS=30
TUIST_TEST_ATTACHMENT_RETENTION_DAYS=30
TUIST_SHARD_BUNDLE_RETENTION_DAYS=14

При использовании Helm-чарта настройте те же периоды хранения в виде карты:

yaml
server:
artifactRetentionDays:
cacheArtifacts: 30
appPreviews: 30
buildArchives: 60
runArtifacts: 30
testAttachments: 30
shardBundles: 14

Все шесть ключей необязательны. В этом примере включены все поддерживаемые типы артефактов с независимыми периодами хранения. Пропустите ключ или оставьте его значение пустым, чтобы оставить очистку отключенной для этого типа артефактов. Для самостоятельно размещаемых экземпляров нет максимального ограничения в 30 дней. Если настроенные значения не являются положительными целыми числами, сервер не запустится.

Перезапустите сервер после изменения переменной хранения. Каждая поставленная в очередь задача очистки на самостоятельно размещаемом экземпляре проверяет текущую конфигурацию перед удалением файлов, поэтому снятие или обнуление переменной, а также увеличение ее периода хранения также защищает файлы от ожидающих задач после перезапуска.

Переменная окружения Файлы артефактов, удаляемые из объектного хранилища
TUIST_CACHE_ARTIFACT_RETENTION_DAYS Кэш Xcode, устаревший кэш с адресацией по содержимому, кэш модулей и файлы кэша Gradle
TUIST_APP_PREVIEW_RETENTION_DAYS Сборки предварительного просмотра приложений и их значки
TUIST_BUILD_ARCHIVE_RETENTION_DAYS Текущие и устаревшие архивы сборок
TUIST_RUN_ARTIFACT_RETENTION_DAYS Все объекты, хранящиеся под префиксом артефактов истекшего запуска, включая пакеты результатов, записи вызовов и архивы сессий
TUIST_TEST_ATTACHMENT_RETENTION_DAYS Вложения запусков тестов
TUIST_SHARD_BUNDLE_RETENTION_DAYS Пакеты шардов тестов

Запланированная очистка удаляет только бинарные объекты артефактов. Она сохраняет соответствующие строки в PostgreSQL и ClickHouse, поэтому метаданные сборок, тестов, запусков, предварительных просмотров и шардов могут оставаться видимыми в дашбордах после истечения срока загрузки. Эта конфигурация не изменяет правила хранения таблиц ClickHouse.

Настройка электронной почты#

Tuist требует функциональности электронной почты для аутентификации пользователей и транзакционных уведомлений (например, сброса пароля, уведомлений об учетной записи). В настоящее время поддерживается только Mailgun в качестве провайдера электронной почты.

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_MAILGUN_API_KEY API-ключ для аутентификации в Mailgun Да* key-1234567890abcdef
TUIST_MAILING_DOMAIN Домен, с которого будут отправляться письма Да* mg.tuist.io
TUIST_MAILING_FROM_ADDRESS Адрес электронной почты, который будет отображаться в поле «От» Да* [email protected]
TUIST_MAILING_REPLY_TO_ADDRESS Необязательный адрес для ответов пользователей Нет [email protected]
TUIST_SKIP_EMAIL_CONFIRMATION Пропустить подтверждение электронной почты при регистрации новых пользователей. При включении пользователи автоматически подтверждаются и могут войти в систему сразу после регистрации Нет true, если электронная почта не настроена, false, если электронная почта настроена true, false, 1, 0

* Переменные настройки электронной почты требуются только если вы хотите отправлять письма. Если они не настроены, подтверждение электронной почты автоматически пропускается

Поддержка SMTP

Общая поддержка SMTP в настоящее время недоступна. Если вам нужна поддержка SMTP для вашего локального развертывания, пожалуйста, свяжитесь с [email protected], чтобы обсудить ваши требования.

Развертывания в изолированных сетях

Для локальных установок без доступа к интернету или настройки провайдера электронной почты подтверждение электронной почты по умолчанию автоматически пропускается. Пользователи могут войти в систему сразу после регистрации. Если у вас настроена электронная почта, но вы все равно хотите пропустить подтверждение, установите TUIST_SKIP_EMAIL_CONFIRMATION=true. Чтобы требовать подтверждение электронной почты, когда она настроена, установите TUIST_SKIP_EMAIL_CONFIRMATION=false.

Квоты электронной почты и ссылки для сброса пароля

Когда электронная почта настроена, приглашения (созданные, массовые или повторные) ограничены одним письмом на получателя каждые пять минут и всплесками по 50 писем с пополнением до 50 в час на организацию и на отправителя. Отмена приглашения не восстанавливает лимит, и API приглашений отвечает на исчерпанный лимит кодами 429 и Retry-After. При наличии нескольких реплик настройте общий Valkey для квот всего развертывания; если он настроен, но недоступен, письма с приглашениями отклоняются. Ссылки для сброса пароля истекают через 15 минут.

Настройка Git-платформы#

Tuist может интегрироваться с Git-платформами, чтобы предоставлять дополнительные возможности, такие как автоматическая публикация комментариев в ваших pull-запросах.

GitHub#

Сервер Tuist с самостоятельным размещением не может установить приложение GitHub, работающее на https://tuist.dev. Приложения GitHub привязаны к серверу, который их зарегистрировал, поэтому вашему развертыванию нужно собственное приложение на github.com.

Регистрация приложения

Создайте приложение GitHub, принадлежащее вашей организации GitHub. Вы можете повторно использовать приложение, созданное для аутентификации, если только вы не создали приложение OAuth. Настройте его следующим образом, заменив YOUR_APP_URL на значение TUIST_APP_URL:

Параметр Значение
URL-адреса обратного вызова YOUR_APP_URL/users/auth/github/callback и YOUR_APP_URL/integrations/github/authorize
URL-адрес настройки YOUR_APP_URL/integrations/github/setup
Перенаправление при обновлении Включено
URL-адрес вебхука YOUR_APP_URL/webhooks/github
Секрет вебхука Любая случайная строка. Вы установите ее как TUIST_GITHUB_APP_WEBHOOK_SECRET

Предоставьте следующие разрешения для репозитория:

Разрешение Доступ
Содержимое Только чтение
Метаданные Только чтение
Задачи (Issues) Чтение и запись
Pull-запросы Чтение и запись
Проверки (Checks) Чтение и запись

Также предоставьте разрешение организации Участники: только чтение. Во время настройки на github.com Tuist проверяет, что человек, подключающий установку организации, является активным владельцем организации GitHub, а не просто пользователем с доступом к одному из ее репозиториев.

Подпишите приложение на события Check run, Pull request и Issue comment.

Оставьте отключенным параметр Запрашивать авторизацию пользователя (OAuth) во время установки, чтобы GitHub отправлял установщиков на URL-адрес настройки. Tuist запускает отдельный шаг авторизации, используя дополнительный обратный вызов /integrations/github/authorize для проверки права владения установкой. Когда установка начинается на GitHub, установщик затем выбирает организацию Tuist. Установки в организации GitHub всегда показывают этот выбор; установки, начатые в Tuist, сохраняют свою организацию.

Настройка сервера

Установите следующие переменные окружения, затем перезапустите сервер:

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_GITHUB_APP_NAME Слаг приложения, который является последним компонентом пути его публичного URL-адреса https://github.com/apps/<slug> Да my-company-tuist
TUIST_GITHUB_APP_ID Числовой идентификатор приложения, используемый для проверки права владения установкой Да 123456
TUIST_GITHUB_APP_CLIENT_ID Идентификатор клиента приложения GitHub Да Iv1.a629723000043722
TUIST_GITHUB_APP_CLIENT_SECRET Секрет клиента приложения Да 232f972951033b89799b0fd24566a04d83f44ccc
TUIST_GITHUB_APP_PRIVATE_KEY_BASE64 Закрытый ключ приложения GitHub в кодировке base64. Предпочтительнее, чем TUIST_GITHUB_APP_PRIVATE_KEY, так как он чувствителен к тому, как ваша платформа обрабатывает символы новой строки Да LS0tLS1CRUdJTiBSU0EgUFJJVkFUR...
TUIST_GITHUB_APP_WEBHOOK_SECRET Секрет вебхука, настроенный в приложении GitHub Нет a4c1e0f2b8d6...
Настройте все необходимые учетные данные приложения

Кнопка Установить приложение GitHub на странице интеграций организации остается неактивной, пока не будут установлены TUIST_GITHUB_APP_NAME, TUIST_GITHUB_APP_CLIENT_ID, TUIST_GITHUB_APP_CLIENT_SECRET и закрытый ключ. Числовой идентификатор TUIST_GITHUB_APP_ID также необходим для проверки права владения установкой. URL-адрес установки содержит слаг приложения, поэтому отсутствие TUIST_GITHUB_APP_NAME особенно приводит к тому, что GitHub отвечает ошибкой 404.

После перезапуска сервера администраторы организации устанавливают приложение и подключают репозитории к проектам, следуя руководству по интеграции с GitHub.

Аутентификация OIDC зависит от этого

Аутентификация OIDC сопоставляет утверждение о репозитории в токене CI с репозиториями, подключенными к вашим проектам, и соединение может быть создано только через установленное приложение GitHub. Завершите настройку выше, прежде чем ваши рабочие процессы CI начнут аутентификацию с помощью OIDC.

Вашему серверу Tuist также необходим исходящий доступ к эмитенту OIDC вашего провайдера CI для получения его ключей подписи:

Провайдер CI Хост
GitHub Actions token.actions.githubusercontent.com
CircleCI oidc.circleci.com
Bitrise token.builds.bitrise.io
GitHub Enterprise Server

Переменные окружения выше настраивают только приложение Tuist для github.com. Чтобы интегрировать Tuist вместо этого с экземпляром GitHub Enterprise Server (GHES), администраторы организации переходят на вкладку Корпоративный сервер на странице интеграций и вводят базовый URL-адрес GHES — Tuist проводит их через процесс регистрации приложения через манифест GitHub для регистрации нового приложения Tuist на их экземпляре GHES. Учетные данные нового приложения хранятся в зашифрованном виде для каждой установки; дополнительные переменные окружения TUIST_GITHUB_APP_* не требуются.

Origin#

Серверу Tuist с самостоятельным размещением требуется собственное приложение Origin, настроенное с использованием URL-адресов вашего развертывания и ключа подписи. Зарегистрируйте отдельное приложение для каждой среды Tuist, чтобы установки и учетные данные оставались независимыми.

Регистрация приложения
  1. Сгенерируйте пару ключей подписи Ed25519 с помощью OpenSSL с поддержкой Ed25519:

    bash
    umask 077
    openssl genpkey -algorithm ED25519 -out origin-app-private.pem
    openssl pkey -in origin-app-private.pem -pubout -out origin-app-public.pem
  2. Создайте приложение в настройках приложения Origin. Зарегистрируйте содержимое origin-app-public.pem в качестве его открытого ключа подписи. Храните origin-app-private.pem в секрете; вы предоставите его серверу Tuist, а не загрузите в Cursor.

  3. Настройте следующие параметры, заменив YOUR_APP_URL на базовый HTTPS URL-адрес вашего развертывания Tuist:

    Параметр Значение
    URL-адрес главной страницы YOUR_APP_URL
    URI перенаправления YOUR_APP_URL/integrations/origin/setup
    URL-адрес вебхука YOUR_APP_URL/webhooks/origin
  4. Скопируйте зарегистрированный идентификатор приложения, который начинается с app_.

Во время установки Tuist запрашивает следующие разрешения:

Область действия Используется для
repository:pull_requests:read Поиск pull-запросов и их текущего головного коммита.
repository:pull_requests:reviews:write Чтение, публикация и обновление комментариев к отчетам. Origin включает соответствующее разрешение на чтение обзоров.
repository:metadata:read Обнаружение репозиториев и чтение их веток по умолчанию. Предоставляется автоматически Origin.

Оставьте необязательные события вебхуков репозитория невыбранными. Уведомлений о жизненном цикле установки достаточно; доступ к исходному коду, разрешения на слияние и разрешения на выполнение проверок не требуются.

Настройка сервера

Установите следующие переменные окружения, затем перезапустите сервер:

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_ORIGIN_APP_ID Идентификатор приложения, скопированный из настроек приложения Origin. Да app_...
TUIST_ORIGIN_APP_PRIVATE_KEY Полное содержимое origin-app-private.pem, включая строки BEGIN PRIVATE KEY и END PRIVATE KEY и все разрывы строк. Да -----BEGIN PRIVATE KEY-----...

Храните закрытый ключ в менеджере секретов вашего развертывания. Сохраняйте его многострочный формат PEM; этот параметр не принимает замену в кодировке base64. Никогда не фиксируйте ключ в системе контроля версий и не раскрывайте его в логах. Обе переменные должны принадлежать одному и тому же зарегистрированному приложению.

Вашему серверу Tuist необходим исходящий HTTPS-доступ к api.cursor.com. Cursor должен иметь возможность доставлять запросы на URL-адрес вебхука, а администраторы должны иметь возможность возвращаться на URI перенаправления в своем браузере. Оба зарегистрированных URL-адреса должны совпадать с базовым HTTPS URL-адресом вашего развертывания.

Установка приложения

После перезапуска сервера администратор открывает Settings → Integrations, выбирает Connect в разделе Origin и предоставляет приложению доступ к соответствующей учетной записи Origin и репозиториям. Организация Tuist сохраняется на протяжении всего процесса. При установке, инициированной непосредственно из Origin, администратору предлагается войти в систему и выбрать организацию Tuist для подключения. Затем он выбирает Add new project connection, чтобы связать проект Tuist с нативным репозиторием.

Следуйте руководству по интеграции Origin для настройки подключений проектов и требований к загрузке результатов. Установка приложения не запускает рабочие процессы сборки или тестирования; эти процессы продолжают отправлять результаты на ваш сервер Tuist.

Entire#

Серверу Tuist с самостоятельным размещением требуется собственный плагин Entire, настроенный с использованием URL-адресов вашего развертывания и ключа подписи. Плагины Entire требуют регистрации партнера, поэтому свяжитесь с Entire перед началом работы. Зарегистрируйте отдельный плагин или, как минимум, отдельный ключ подписи для каждой среды Tuist, чтобы установки и учетные данные оставались независимыми.

Регистрация плагина
  1. Сгенерируйте пару ключей подписи Ed25519 с помощью OpenSSL с поддержкой Ed25519:

    bash
    umask 077
    openssl genpkey -algorithm ED25519 -out entire-plugin-private.pem
    openssl pkey -in entire-plugin-private.pem -pubout -out entire-plugin-public.pem
  2. Зарегистрируйте плагин, следуя руководству по регистрации плагинов Entire. Предоставьте содержимое entire-plugin-public.pem или URL-адрес JWKS, который его публикует, в качестве ключа подписи плагина. Храните entire-plugin-private.pem в секрете; вы предоставите его серверу Tuist, а не Entire.

  3. Настройте следующие URL-адреса, заменив YOUR_APP_URL на базовый HTTPS URL-адрес вашего развертывания Tuist:

    Параметр Значение
    URL-адрес после установки YOUR_APP_URL/integrations/entire/callback
    URL-адрес вебхука YOUR_APP_URL/webhooks/entire
  4. Запишите slug плагина, подтвержденный Entire, и предоставленный им URL-адрес ключа подписи вебхука.

Запросите следующие разрешения:

Разрешение Используется для
contents:read Получение событий Trail и поиск открытых и черновых Trails с их головными коммитами.
checks:write Публикация гейта Tuist.
findings:write Публикация и устранение находок неудачных и нестабильных тестов.
discussions:write Публикация и обновление сводного комментария. Установки, которые не предоставили это разрешение, все равно получают гейт и находки.

Доступ на запись к репозиторию не требуется. Если вы добавляете разрешения к существующей регистрации, попросите Entire обновить ее и подтвердите, что установки предоставляют новые разрешения. См. контракты Entire: Checks, Findings и Trail comments.

Настройка сервера

Установите следующие переменные окружения, затем перезапустите сервер:

Переменная окружения Описание Обязательно По умолчанию Пример
TUIST_ENTIRE_PLUGIN_SLUG Slug плагина, подтвержденный Entire. Да tuist
TUIST_ENTIRE_PLUGIN_PRIVATE_KEY Полное содержимое entire-plugin-private.pem, включая строки BEGIN PRIVATE KEY и END PRIVATE KEY и все разрывы строк. Да -----BEGIN PRIVATE KEY-----...
TUIST_ENTIRE_DELIVERY_JWKS_URL URL-адрес ключа подписи вебхука, предоставленный Entire при регистрации. Да
TUIST_ENTIRE_PLUGIN_KEY_ID ID ключа, если вы зарегистрировали ключ подписи через JWKS. Нет
TUIST_ENTIRE_CORE_URL URL-адрес Entire Core, используемый для запросов установки. Нет https://eu.auth.entire.io

Храните закрытый ключ в менеджере секретов вашего развертывания и сохраняйте его многострочный формат PEM. Никогда не добавляйте ключ в систему контроля версий и не раскрывайте его в логах. С чартом Tuist Helm вы можете вместо этого хранить PEM в хранилище 1Password как ENTIRE_PLUGIN/private_key и включить server.config.entirePluginKey.enabled вместе с server.config.managedSecrets; имена элемента и поля настраиваются через server.config.entirePluginKey.item и .field. Это сопоставление не устанавливает slug или URL-адрес ключа подписи вебхука.

Вашему серверу Tuist требуется исходящий HTTPS-доступ к Entire Core и к региональным хостам API Entire, которые обслуживают ваши репозитории, все в доменах entire.io или entire.com. Tuist проверяет квитанции об установке и подписи вебхуков, выпускает краткосрочные токены с областью действия репозитория и никогда не встраивает токены в ссылки отчетов.

Включение интеграции

Примените миграции сервера перед развертыванием приложения, затем включите флаг функции entire_trails глобально, чтобы предложить интеграцию всем аккаунтам, или только выбранным аккаунтам. Включение флага не меняет тех, кто может установить плагин в Entire; чтобы предложить его вне проекта Entire, владеющего плагином, попросите вашего контактного лица в Entire разрешить это. Интеграция не зависит от конфигурации выполнения CI в Tuist.

Если вы откатываете приложение, сохраните таблицу entire_trail_reports, чтобы последующее обновление могло восстановить публикации, которые были в процессе.

Администраторы затем устанавливают плагин и подключают репозитории к проектам, следуя руководству по интеграции с Entire. Установка плагина не запускает рабочие процессы сборки или тестирования; эти рабочие процессы продолжают отправлять результаты на ваш сервер Tuist.

Локальное тестирование#

Мы предоставляем исчерпывающую конфигурацию Docker Compose, которая включает все необходимые зависимости для тестирования сервера Tuist на вашем локальном компьютере перед развертыванием в вашей инфраструктуре:

  • PostgreSQL 15
  • ClickHouse 26.5 для аналитики
  • ClickHouse Keeper для координации
  • MinIO для S3-совместимого хранилища
  • Kura для локального тестирования самодостаточного кэша
  • pgweb для администрирования базы данных
Требуется лицензия

Для запуска сервера Tuist, включая экземпляры локальной разработки, юридически требуется действительная переменная окружения TUIST_LICENSE. Если вам нужна лицензия, пожалуйста, свяжитесь с нами по адресу [email protected].

Быстрый старт:

  1. Скачайте файлы конфигурации:

    bash
    curl -O https://tuist.dev/server/self-host/docker-compose.yml
    curl -O https://tuist.dev/server/self-host/clickhouse-config.xml
    curl -O https://tuist.dev/server/self-host/clickhouse-log-level.xml
    curl -O https://tuist.dev/server/self-host/clickhouse-log-ttl.xml
    curl -O https://tuist.dev/server/self-host/clickhouse-keeper-config.xml
    curl -O https://tuist.dev/server/self-host/.env.example
  2. Настройте переменные окружения:

    bash
    cp .env.example .env
    # Edit .env and add your TUIST_LICENSE, TUIST_SECRET_KEY_BASE, and authentication credentials

    Встроенная служба ClickHouse принимает следующие необязательные элементы управления операционными логами:

    Переменная окружения Описание По умолчанию Пример
    CLICKHOUSE_SYSTEM_LOG_TTL_DAYS Окно хранения в днях для таблиц логов ClickHouse system.*, таких как text_log, query_log, trace_log, metric_log и part_log 14 7
    CLICKHOUSE_TEXT_LOG_LEVEL Логгер сервера ClickHouse и уровень system.text_log information warning
    CLICKHOUSE_SUPERSEDED_LOG_TABLES Что делать с таблицами <name>_N, которые ClickHouse оставляет после замены системной таблицы логов. ignore сохраняет их, delete удаляет их ignore delete
  3. Запустите все службы:

    bash
    docker compose up -d
    # or with podman:
    podman compose up -d

    На Apple Silicon Docker Desktop автоматически загружает варианты образов Tuist и зависимостей для архитектуры linux/arm64. Чтобы принудительно использовать эмуляцию amd64 для отладки, запустите Compose с переменной DOCKER_DEFAULT_PLATFORM=linux/amd64.

    Встроенный файл compose использует именованные тома Docker для хранения постоянных данных. Если вы замените их привязками к хосту, сначала создайте соответствующие директории на хосте и предоставьте права на запись пользователям контейнера, особенно для директорий данных ClickHouse и ClickHouse Keeper.

  4. Откройте сервер по адресу http://localhost:8080

Конечные точки служб:

Часто используемые команды:

Проверить статус служб:

bash
docker compose ps
# or: podman compose ps

Просмотреть логи:

bash
docker compose logs -f tuist

Остановить службы:

bash
docker compose down

Сбросить всё (удаляет все данные):

bash
docker compose down -v

Файлы конфигурации:

Kubernetes с Helm#

Tuist предоставляет официальный Helm-чарт для развертывания в Kubernetes. Чарт включает сервер Tuist и службу кэша, а также встроенные инфраструктурные зависимости, которые при необходимости можно заменить на внешние провайдеры.

Установка чарта#

bash
helm install tuist oci://ghcr.io/tuist/charts/tuist \
--set server.license.key="YOUR_LICENSE_KEY"

Чтобы зафиксировать конкретную версию чарта:

bash
helm install tuist oci://ghcr.io/tuist/charts/tuist \
--set server.license.key="YOUR_LICENSE_KEY" \
--version 0.1.0

Лицензия#

Значение server.license.key принимает как стандартный ключ лицензии, так и Base64-кодированный сертификат лицензии для изолированных установок; сервер автоматически определяет тип.

Передача лицензии через --set подходит для быстрой установки. Если вы храните значения в системе контроля версий, сохраните лицензию в Kubernetes Secret, управляемом вне Helm (например, с помощью Vault, Sealed Secrets или SOPS), и укажите на него в чарте:

yaml
# values.yaml
server:
license:
existingSecret: tuist-license
existingSecretKeys:
key: TUIST_LICENSE
certificateBase64: ""

Запись в разделе existingSecretKeys.key указывает поле в вашем Secret, содержащее значение лицензии (ключ лицензии или Base64-кодированный сертификат для изолированных установок). Каждое поле в разделе existingSecretKeys по умолчанию совпадает с именем ключа в чарте, поэтому для отсутствующих в вашем Secret полей задайте пустую строку, как показано выше для certificateBase64. В противном случае поды будут ссылаться на несуществующие ключи и не смогут запуститься. Создайте Secret в пространстве имен релиза перед установкой или обновлением чарта.

Настройте лицензию только из одного источника: server.license.key или server.license.existingSecret. Чарт не сможет сформировать манифест, если источник не указан или если источники комбинируются. Лицензия, переданная через server.extraEnv, не считается источником, поэтому используйте вместо этого existingSecret.

Инфраструктурные зависимости#

Чарт управляет тремя инфраструктурными зависимостями: postgresql, clickhouse и objectStorage. По умолчанию каждая работает в режиме embedded, то есть разворачивается внутри кластера. Чтобы использовать свои внешние экземпляры, установите для зависимости параметр mode в значение external и заполните данные подключения в файле values.yaml. Например, чтобы использовать внешнюю базу данных PostgreSQL:

yaml
# values.yaml
postgresql:
mode: external
external:
host: your-db-host
port: 5432
database: tuist
username: tuist
password: your-password

Если вы управляете учетными данными PostgreSQL вне Helm, укажите в чарте на существующий Kubernetes Secret:

yaml
# values.yaml
postgresql:
mode: external
external:
port: 5432
database: tuist
existingSecret: tuist-postgresql
existingSecretKeys:
host: host
username: username
password: password

Чарт считывает хост, имя пользователя и пароль из Secret и формирует DATABASE_URL через подстановку переменных окружения Kubernetes, поэтому пароль не попадает в манифест Helm. Значение пароля в Secret должно быть безопасным для URL, так как оно вставляется в строку подключения к базе данных.

Та же схема применяется к clickhouse и objectStorage. Полный список настраиваемых полей см. в блоке external каждого раздела в файле values.yaml чарта.

Общие настройки планирования и метки#

Чарт предоставляет небольшой набор общих настроек подов через раздел global, чтобы операторы могли адаптировать развертывание под свой кластер без дублирования значений для каждой рабочей нагрузки:

yaml
global:
podLabels:
environment: production
imagePullSecrets:
- name: ghcr-pull-secret
nodeSelector:
nodepool: apps
tolerations:
- key: dedicated
operator: Equal
value: apps
effect: NoSchedule

Используйте эти настройки, если вам нужно:

  • добавить специфичные для кластера метки ко всем подам
  • загружать зеркалированные образы из приватного реестра
  • нацеливаться на выделенный пул узлов
  • разрешать размещение подов на tainted-узлах, зарезервированных для рабочих нагрузок Tuist

Идентификация рабочих нагрузок и сервисные аккаунты#

Чарт ограничивает область действия сервисных аккаунтов каждой рабочей нагрузкой приложения, чтобы вы могли предоставлять идентичность только там, где это необходимо:

  • server.serviceAccount применяется к развертыванию сервера Tuist и задаче миграции
  • cache.serviceAccount применяется к развертыванию кэша

Например, когда кэш использует внешний S3-бакет в EKS, вы можете включить IRSA для рабочей нагрузки кэша, не прикрепляя ту же IAM-роль к встроенным базам данных:

yaml
cache:
serviceAccount:
create: true
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/tuist-cache

Переопределения для совместимости#

Чарт оставляет специфичные для хранилища и service mesh настройки опциональными, чтобы значения по умолчанию оставались переносимыми:

yaml
cache:
podSecurityContext:
fsGroup: 990
clickhouse:
embedded:
service:
nativePort: 9100
systemLogs:
ttlDays: 7
supersededTables: delete
level: warning

Используйте эти переопределения только если ваш кластер требует их:

  • cache.podSecurityContext по умолчанию пуст. Установите fsGroup, если вашему классу хранения или CSI-драйверу требуется общее групповое владение на смонтированных томах.
  • clickhouse.embedded.service.nativePort по умолчанию равен стандартному порту нативного сервиса ClickHouse 9000 и может быть изменен, если service mesh или резерв платформы конфликтует с этим портом.
  • clickhouse.embedded.systemLogs.ttlDays по умолчанию пуст, оставляя неограниченное хранение в ClickHouse для встроенных внутренних таблиц логов, таких как system.text_log, system.query_log, system.trace_log, system.metric_log и system.part_log. Установка этого параметра один раз заменяет эти таблицы, поэтому используйте его вместе с supersededTables: delete — см. ограничение срока хранения операционных логов.
  • clickhouse.embedded.systemLogs.level по умолчанию равен information для встроенного логгера сервера ClickHouse и system.text_log. В отличие от ttlDays, он не является частью определения таблицы, поэтому его изменение никогда не заменяет таблицу.
  • clickhouse.embedded.systemLogs.supersededTables по умолчанию равен ignore и определяет, что происходит с таблицами <name>_N, которые ClickHouse оставляет после замены системной таблицы логов. Установите значение delete, чтобы удалять их при каждом helm upgrade.
  • Изменения ttlDays и level применяются к поду ClickHouse при следующем перезапуске, так как оба являются монтированиями subPath, и чарт не выполняет rolling update StatefulSet при изменении его ConfigMap.

Наблюдаемость#

Чарт включает опциональный стек наблюдаемости (OpenTelemetry Collector, Prometheus, Grafana, Loki и Tempo). Он отключен по умолчанию. Чтобы включить его в вашем values.yaml:

yaml
# values.yaml
observability:
enabled: true

При включении Grafana доступна с предварительно настроенными детализациями для логов, трейсов и метрик. Для внешней наблюдаемости оставьте это отключенным и настройте эндпоинты через server.extraEnv:

yaml
# values.yaml
server:
extraEnv:
- name: TUIST_OTEL_EXPORTER_OTLP_ENDPOINT
value: "http://your-otel-collector:4317"
- name: TUIST_LOKI_URL
value: "http://your-loki:3100"

Справочник значений#

Полный список настраиваемых значений см. в файле чарта values.yaml.

Развертывание#

Официальный Docker-образ Tuist доступен по адресу:

yaml
ghcr.io/tuist/tuist

Опубликованный образ включает встроенную обработку сборок Linux для архивов .xcactivitylog, поэтому самостоятельные развертывания могут обрабатывать сборки без запуска дополнительных сервисов — задача Oban ProcessBuildWorker выполняется внутри процесса на каждом поде сервера. Если вы хотите вынести обработку сборок на выделенный набор реплик (например, чтобы масштабировать пропускную способность парсинга независимо от веб-уровня), установите processor.enabled: true в Helm-чарте: чарт развернет тот же образ как потребителя только очереди (TUIST_PROCESSOR_MODE=true). Полный список параметров см. в values.yaml.

Note

Парсинг .xcresult опирается на xcresulttool из Xcode, поэтому может выполняться только на macOS. CLI обрабатывает это прозрачно для самостоятельных развертываний: tuist test по умолчанию использует режим обработки local для любого сервера, кроме tuist.dev, парся xcresult на машине разработчика (где уже установлен Xcode для самой сборки) и загружая структурированные результаты. Результаты тестов принимаются без дополнительной инфраструктуры.

Загрузка Docker-образа#

Вы можете получить образ, выполнив следующую команду:

bash
docker pull ghcr.io/tuist/tuist:latest

Образ опубликован для архитектур linux/amd64 и linux/arm64, поэтому Docker автоматически выбирает нативную Linux-архитектуру для хоста.

Или загрузите конкретную версию:

bash
docker pull ghcr.io/tuist/tuist:0.1.0

Развертывание Docker-образа#

Процесс развертывания Docker-образа будет отличаться в зависимости от выбранного облачного провайдера и подхода вашей организации к непрерывному развертыванию. Поскольку большинство облачных решений и инструментов, таких как Kubernetes, используют Docker-образы в качестве базовых единиц, примеры в этом разделе должны хорошо соответствовать вашей текущей конфигурации.

Warning

Если вашему конвейеру развертывания нужно проверить, что сервер запущен и работает, вы можете отправить HTTP-запрос GET к /ready и проверить код состояния 200 в ответе.

Fly#

Для развертывания приложения на Fly вам потребуется файл конфигурации fly.toml. Рассмотрите возможность его динамической генерации в вашем конвейере непрерывного развертывания (CD). Ниже приведен справочный пример для вашего использования:

toml
app = "tuist"
primary_region = "fra"
kill_signal = "SIGINT"
kill_timeout = "5s"
[experimental]
auto_rollback = true
[env]
# Your environment configuration goes here
# Or exposed through Fly secrets
[processes]
app = "/usr/local/bin/hivemind /app/Procfile"
[[services]]
protocol = "tcp"
internal_port = 8080
auto_stop_machines = false
auto_start_machines = false
processes = ["app"]
http_options = { h2_backend = true }
[[services.ports]]
port = 80
handlers = ["http"]
force_https = true
[[services.ports]]
port = 443
handlers = ["tls", "http"]
[services.concurrency]
type = "connections"
hard_limit = 100
soft_limit = 80
[[services.http_checks]]
interval = 10000
grace_period = "10s"
method = "get"
path = "/ready"
protocol = "http"
timeout = 2000
tls_skip_verify = false
[services.http_checks.headers]
[[statics]]
guest_path = "/app/public"
url_prefix = "/"

Затем вы можете выполнить fly launch --local-only --no-deploy для запуска приложения. При последующих развертываниях вместо выполнения fly launch --local-only вам нужно будет выполнить fly deploy --local-only. Fly.io не позволяет загружать приватные Docker-образы, поэтому нам нужно использовать флаг --local-only.

Метрики Prometheus#

Tuist предоставляет метрики Prometheus по адресу /metrics, чтобы помочь вам отслеживать работу вашего self-hosted экземпляра. Эти метрики включают:

Метрики HTTP-клиента Finch#

Tuist использует Finch в качестве HTTP-клиента и предоставляет детальные метрики о HTTP-запросах:

Метрики запросов#

  • tuist_prom_ex_finch_request_count_total - Общее количество запросов Finch (счетчик)
    • Метки: finch_name, method, scheme, host, port, status
  • tuist_prom_ex_finch_request_duration_milliseconds - Длительность HTTP-запросов (гистограмма)
    • Метки: finch_name, method, scheme, host, port, status
    • Диапазоны: 10 мс, 50 мс, 100 мс, 250 мс, 500 мс, 1 с, 2,5 с, 5 с, 10 с
  • tuist_prom_ex_finch_request_exception_count_total - Общее количество исключений запросов Finch (счетчик)
    • Метки: finch_name, method, scheme, host, port, kind, reason

Метрики очереди пула соединений#

  • tuist_prom_ex_finch_queue_duration_milliseconds - Время ожидания в очереди пула соединений (гистограмма)
    • Метки: finch_name, scheme, host, port, pool
    • Диапазоны: 1 мс, 5 мс, 10 мс, 25 мс, 50 мс, 100 мс, 250 мс, 500 мс, 1 с
  • tuist_prom_ex_finch_queue_idle_time_milliseconds - Время простоя соединения перед использованием (гистограмма)
    • Метки: finch_name, scheme, host, port, pool
    • Диапазоны: 10 мс, 50 мс, 100 мс, 250 мс, 500 мс, 1 с, 5 с, 10 с
  • tuist_prom_ex_finch_queue_exception_count_total - Общее количество исключений очереди Finch (счетчик)
    • Метки: finch_name, scheme, host, port, kind, reason

Метрики соединений#

  • tuist_prom_ex_finch_connect_duration_milliseconds - Время на установление соединения (гистограмма)
    • Метки: finch_name, scheme, host, port, error
    • Диапазоны: 10 мс, 50 мс, 100 мс, 250 мс, 500 мс, 1 с, 2,5 с, 5 с
  • tuist_prom_ex_finch_connect_count_total - Общее количество попыток соединения (счетчик)
    • Метки: finch_name, scheme, host, port

Метрики отправки#

  • tuist_prom_ex_finch_send_duration_milliseconds - Время на отправку запроса (гистограмма)
    • Метки: finch_name, method, scheme, host, port, error
    • Диапазоны: 1 мс, 5 мс, 10 мс, 25 мс, 50 мс, 100 мс, 250 мс, 500 мс, 1 с
  • tuist_prom_ex_finch_send_idle_time_milliseconds - Время простоя соединения перед отправкой (гистограмма)
    • Метки: finch_name, method, scheme, host, port, error
    • Диапазоны: 1 мс, 5 мс, 10 мс, 25 мс, 50 мс, 100 мс, 250 мс, 500 мс

Все гистограммные метрики предоставляют варианты _bucket, _sum и _count для детального анализа.

Другие метрики#

Помимо метрик Finch, Tuist предоставляет метрики для:

  • Производительности виртуальной машины BEAM
  • Пользовательских бизнес-метрик (хранилище, аккаунты, проекты и т. д.)
  • Производительности базы данных (при использовании инфраструктуры, размещенной Tuist)

Операции#

Tuist предоставляет набор утилит по адресу /ops/, которые можно использовать для управления вашим экземпляром.

Авторизация

Только пользователи, чей домен электронной почты совпадает с TUIST_OPERATOR_EMAIL_DOMAIN, могут обращаться к конечным точкам /ops/. Если переменная не установлена, доступ к ним закрыт для всех. Укажите домен, почтовыми ящиками которого вы управляете.

Пользователь также должен подтвердить владение адресом: перейдя по ссылке из письма с подтверждением или сбросом пароля, войдя через Google, GitHub или Apple, введя одноразовый код или предоставив проверенный email при входе агента. Аккаунты, подтвержденные автоматически (это поведение по умолчанию без почтового провайдера), не считаются подтвержденными, пока пользователь не выполнит одно из этих действий. После создания аккаунта подтверждение фиксируется только пока адрес находится в TUIST_OPERATOR_EMAIL_DOMAIN, поэтому после установки или изменения переменной операторам, которые еще не подтвердили свой адрес в этом домене, нужно сделать это снова. Аккаунты, созданные через вход одним из этих провайдеров или через вход агента, сохраняют подтверждение с момента создания. Без почтового провайдера аккаунт, зарегистрированный с паролем, не может привязать одного из этих провайдеров, поэтому создавайте аккаунты операторов, входя через Google, GitHub или Apple, либо настройте почтовый провайдер.

Аккаунты, созданные до появления этой проверки, еще не зафиксировали такое подтверждение, поэтому существующий оператор восстановит доступ после сброса пароля или однократного входа через одного из этих провайдеров.

Когда аккаунт в домене операторов впервые подтверждает адрес таким способом, не имея ранее подтверждения, Tuist удаляет его пароль, ключи доступа и ссылки на провайдеры единого входа организации, а также выполняет выход из браузера и CLI, поскольку тот, кто зарегистрировал адрес, может не быть его владельцем. Сброс пароля для такого аккаунта делает то же самое, за исключением установки нового пароля. Приложение-аутентификатор, настроенное на аккаунте, остается; если оно не принадлежит владельцу, удалите его. Подтвержденные аккаунты вне домена операторов сохраняют свои учетные данные. Владелец продолжает входить через провайдера или устанавливает новый пароль через сброс.

Аккаунты, созданные или переименованные через SCIM-провижининг, не имеют подтверждения, пока владелец не предоставит его.

  • Ошибки (/ops/errors): Вы можете просматривать непредвиденные ошибки, возникшие в приложении. Это полезно для отладки и понимания причин сбоев; мы можем попросить вас поделиться этой информацией, если вы столкнулись с проблемами.
  • Дашборд (/ops/dashboard): Вы можете просматривать дашборд, который предоставляет информацию о производительности и состоянии приложения (например, потребление памяти, запущенные процессы, количество запросов). Этот дашборд помогает понять, достаточно ли ресурсов используемого оборудования для обработки нагрузки.