Сервер

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

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

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

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

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

Граница обновления и отката 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 совместимости и убедитесь, что не осталось бинарных файлов, читающих кэш, перед удалением инвалидаций. Не допускайте, чтобы плавающий тег образа пропустил этот этап во время автоматического обновления. Новые установки без старых потребителей не нуждаются в промежуточном развертывании.

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

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

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

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 без поиска живых Secrets не могут сохранить это сгенерированное значение; они должны использовать cookieExistingSecret, подкрепленный отдельно управляемым, стабильным Secret. Не меняйте ключ cookie для неявной ротации работающего кластера. Ротация cookie требует скоординированной миграции/перезапуска каждого участника; обновление только Secret не обновляет существующие процессы.

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

Разрешите EPMD (TCP 4369) и настроенный порт распределения только между доверенными узлами сервера, никогда — от рабочих нагрузок арендаторов или из публичной сети. Проверьте фактическую изоляцию входящего/исходящего трафика в вашей среде; применение NetworkPolicy не доказывает его принудительное исполнение или доступность бэкенда. Канареечное развертывание из двух реплик под постоянной нагрузкой должно успешно пройти присоединение, поэтапную замену и восстановление после сбоев перед переводом в продакшн. DNS используется для обнаружения узлов, а не для отключения исправных узлов при временных сбоях или неполных ответах; правила предотвращения потери реальных узлов и разделения OTP остаются в силе. libcluster может регистрировать успешную операцию «отключено» для обратного вызова удержания без закрытия соединения; определяйте фактическое членство по событиям подключения/отключения узлов или Node.list(), а не только по этой строке лога.

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

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

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

Доступ с доверием к сети#

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

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

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

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

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

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. Очистка кэша и загрузка удаленных артефактов по-прежнему требуют учетных данных. Клиенты без поддержки должны продолжать аутентификацию.
• Bazel: Для отчетности требуется явное указание TUIST_BAZEL_BES_BACKEND и совместимая Kura. Опции кэша и отчетности включаются независимо. Повторно запустите tuist bazel setup после изменения учетных данных или любой из этих настроек; повторно запустите tuist cache config для изменений конфигурации кэша компиляции.

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

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

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

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

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

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

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

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

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

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

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

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

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

Tuist использует ClickHouse для хранения и запроса больших объемов аналитических данных. ClickHouse обязателен для таких функций, как аналитика сборок. Вы можете выбрать самостоятельное размещение 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 пишет на локальный диск только одной реплики; многорепличная настройка либо незаметно разделит прием данных между репликами, либо отклонит команду CREATE с ошибкой 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 переименовывает каждую из них и создает новую таблицу, как описано в разделе замещенные таблицы журналов. Оставленная версия содержит все накопленные на данный момент данные и не имеет собственного срока хранения, поэтому, если вы не освободите место на том же шаге, она останется на диске навсегда, а новое окно будет ограничивать только строки, записанные с этого момента. Включите обе настройки вместе:

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

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

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

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

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

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

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

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

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

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

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

Хранение#

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

Узлы 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_DATABASE_SCHEMA не равно public, миграции релиза создают схему, если она еще не существует, перед запуском цепочки миграций Ecto. Если роль миграции не может создавать схемы, создайте схему заранее и сделайте роль миграции ее владельцем.

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

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

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

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

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

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

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

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:

Google#

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

Okta#

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

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

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

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

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

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

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

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

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:

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

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

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

В Helm-чарте настройте те же окна в виде карты:

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

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

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

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

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

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

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

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

GitHub#

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

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

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

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

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

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

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

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

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

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

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

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

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

GitHub Enterprise Server

Переменные окружения выше настраивают только приложение Tuist для github.com. Чтобы интегрировать Tuist с экземпляром GitHub Enterprise Server (GHES), администраторы организации переходят на вкладку Enterprise server на странице интеграций и вводят базовый 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. Скопируйте зарегистрированный ID приложения, который начинается с app_.

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

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

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

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

Храните закрытый ключ в менеджере секретов вашего развертывания. Сохраняйте его многострочный формат 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.

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

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

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

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

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

   bash

   curl -O https://docs.tuist.io/server/self-host/docker-compose.yml

   curl -O https://docs.tuist.io/server/self-host/clickhouse-config.xml

   curl -O https://docs.tuist.io/server/self-host/clickhouse-log-level.xml

   curl -O https://docs.tuist.io/server/self-host/clickhouse-log-ttl.xml

   curl -O https://docs.tuist.io/server/self-host/clickhouse-keeper-config.xml

   curl -O https://docs.tuist.io/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

Эндпоинты сервисов:

• Сервер Tuist: http://localhost:8080
• Кэш Kura (HTTP + REAPI gRPC на одном порту): http://localhost:4000
• Консоль MinIO: http://localhost:9003 (учетные данные: tuist / tuist_dev_password)
• API MinIO: http://localhost:9002
• pgweb (интерфейс PostgreSQL): http://localhost:8081
• Метрики Prometheus: http://localhost:9091/metrics
• ClickHouse HTTP: http://localhost:8124

Основные команды:

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

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

Остановить сервисы:

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

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

• docker-compose.yml — полная конфигурация Docker Compose
• clickhouse-config.xml — конфигурация ClickHouse
• clickhouse-keeper-config.xml — конфигурация ClickHouse Keeper
• .env.example — пример файла переменных окружения

Kubernetes с Helm#

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

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

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

Лицензия#

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

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

Запись в 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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• 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:

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

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

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

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

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

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

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

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

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

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

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

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

Fly#

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

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

Метрики Prometheus#

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

Метрики 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/, которые можно использовать для управления вашим экземпляром.

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