ispmanager 6 lite, pro, host

/
/
/
Клонирование проекта из Git-репозитория

Клонирование проекта из Git-репозитория

Модуль Git копирует проект из Git-репозитория на сервер с ispmanager и публикует его на сайте. Поддерживается подключение репозиториев из любых Git-систем с доступом по HTTPS или SSH. Примеры в статье приведены для GitHub.

Как работает модуль Git

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

Проект существует в трех копиях:

  • удаленный репозиторий — хранится в вашей Git-системе, например в GitHub. Здесь вы пишете и сохраняете код
  • рабочая директория — копия репозитория на сервере с ispmanager. Панель обновляет ее командой Pull
  • директория развертывания — из нее сайт отдает файлы посетителям. Панель обновляет ее командой Deploy

Загрузка проекта проходит в четыре этапа:

1. Вы указываете адрес репозитория, ветку и данные доступа, если репозиторий приватный.
2. Панель клонирует проект из репозитория в рабочую директорию.
3. Панель запускает команды развертывания: собирает проект, если вы добавили команды сборки, копирует файлы в директорию развертывания и при необходимости перезапускает приложение.
4. Сайт готов. Для нового сайта панель дополнительно выпускает SSL-сертификат.

Когда вы вносите изменения в репозиторий, на сайт они попадают одним из двух способов: 

  • автоматически — панель получает уведомление от Git-системы через веб-хук и обновляет сайт сама
  • вручную — вы нажимаете Pull, затем Deploy

Все команды выполняются от имени пользователя-владельца сайта.

Требования модуля Git

  • Тариф ispmanager: лайт, про или хост
  • Версия ispmanager: 6.153 или выше
  • Уровень доступа: пользователь

  • Установленные утилиты: git

    Как проверить, установлена ли git
    1. Авторизуйтесь в панели под учетной записью уровня администратор или выше.
    2. Перейдите в раздел Конфигурация ПО.
    3. Найдите в списке Git.

    Если утилита установлена, в столбце Статус будет стоять галочка. Если нет — выделите Git и на панели инструментов нажмите иконка "Установить ПО".

Установка модуля Git

Модуль устанавливается автоматически при установке панели с рекомендуемым ПО и при ее обновлении, если на сервере установлена утилита git.

Если модуля нет, установите его вручную:

  1. Авторизуйтесь в панели под учетной записью уровня администратор или выше.
  2. Перейдите в раздел Конфигурация ПО.
  3. Выберите в списке Git.
  4. На панели инструментов нажмите иконка "Установить ПО".

У пользователя www-root доступ к модулю Git будет включен по умолчанию. Для остальных пользователей включите модуль по инструкции.

Включение доступа к Git для пользователя

Если пользователь принадлежит реселлеру, сначала включите возможность для реселлера.

  1. Авторизуйтесь в панели под учетной записью уровня реселлер или выше.
  2. Перейдите в раздел Пользователи.
  3. Выберите пользователя в списке.
  4. На панели инструментов нажмите иконка "Изменить параметры пользователя".
  5. В блоке Доступ установите галочку Может подключать Git-репозитории.
  6. Если пользователю нужны свои команды развертывания, включите для него опцию Может использовать shell.
  7. Сохраните изменения.

Подключение репозитория к сайту

Репозиторий можно подключить: 

  • к новому сайту при создании — если нужно развернуть проект в корневую директорию сайта
  • к существующему сайту — если нужно развернуть проект не в корневую директорию или подключить дополнительный репозиторий

К одному сайту можно подключить несколько репозиториев, а один и тот же репозиторий — к нескольким сайтам.

Чтобы подключить репозиторий:

  1. Перейдите в раздел Сайты.

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

    На панели инструментов нажмите Создать сайт → Git.

    В списке сайтов выберите сайт и в контекстном меню иконка "Контекстное меню" (три точки) выберите Git-репозитории. На панели инструментов нажмите Создать.

  3. Заполните поля и сохраните изменения. Обязательные поля отмечены звездочками.

Поля только для нового сайта:

  • Доменное имя* — имя, по которому посетители открывают сайт.
  • Владелец сайта* — пользователь, от имени которого работает сайт.
  • Обработчик* — программа, которая выполняет скрипты сайта. Список зависит от установленного ПО.
  • Версия обработчика — версия выбранного обработчика.

Доступ к репозиторию:

  • URL репозитория* — адрес репозитория. Для HTTPS: https://ДОМЕН_GIT-СИСТЕМЫ/ПУТЬ_К_РЕПОЗИТОРИЮ.git. Для SSH: git@ДОМЕН_GIT-СИСТЕМЫ:ПОЛЬЗОВАТЕЛЬ/РЕПОЗИТОРИЙ.git.
  • Имя репозитория* — имя, как оно указано в Git-системе.
  • Ветка — ветка, которую нужно клонировать. Если оставить поле пустым, будет клонирована ветка по умолчанию.
  • Публичный репозиторий — отметьте, если для чтения авторизация не нужна.

  • Нужна авторизация — отметьте для приватного репозитория и выберите способ авторизации:

    Этот способ авторизации подходит для российских Git-систем без обязательной двухфакторной аутентификации и Git-серверов в закрытых сетях.

    Этот способ авторизации подходит для GitHub, GitLab и Bitbucket.

    Для авторизации нажмите Авторизоваться в баннере под полем Нужна авторизация и разрешите ispmanager доступ к вашему аккаунту в Git-системе:

    Токен для авторизации хранится в панели в зашифрованном виде и обновляется автоматически, когда истекает срок его действия.

    Этот способ авторизации поддерживается такими популярными Git-системами, как GitHub, GitLab, Bitbucket и т. д. 

    Для авторизации заполните поля: 

    • Логин — имя пользователя или электронная почта вашего личного кабинета в Git-системе

    • Пароль — токен, сгенерированный в Git-системе 

      Как сгенерировать токен
      1. Авторизуйтесь на GitHub.
      2. Нажмите на значок профиля в правом верхнем углу.
      3. Перейдите в раздел Settings → Developer Settings.
      4. В меню слева выберите Personal Access Tokens → Fine-grained tokens.
      5. Нажмите Generate new token и заполните поля:
        • Token name — произвольное название токена
        • Expiration — срок действия: 
          • 7/30/60/90 days — 7/30/60/90 дней
          • Custom — собственный срок действия
          • No expiration — бессрочный
        • Repository access — репозиторий или репозитории, к которым получит доступ токен:
          • Public repositories — публичные репозитории, будут доступны только для чтения
          • All repositories — все существующие и еще не созданные репозитории. Публичные будут доступны только для чтения
          • Only select repositories — только репозитории, отмеченные в списке галочкой
        • Permissions — права доступа. Нажмите Add permissions и отметьте в списке Contents (доступ к коду: файлам, коммитам, веткам, тегам). Установите для Contents в поле Access уровень доступа Read-only.
      6. Нажмите Generate token.
      7. Скопируйте сгенерированный токен. Больше GitHub его не покажет.
      8. При истечении срока действия токена сгенерируйте его заново. Иначе доступ к репозиторию будет заблокирован.

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

    Как добавить SSH-ключ
    1. Авторизуйтесь на GitHub.
    2. Перейдите в нужный репозиторий.
    3. На панели инструментов нажмите иконка шестеренка Settings. 
    4. В меню слева выберите Deploy Keys.
    5. Нажмите Add deploy key и заполните поля:
      • Title — произвольное название ключа
      • Key — скопированный в ispmanager ключ
      • Allow write access — оставьте выключенным
    6. Нажмите Add key.

Синхронизация и развертывание:

  • Директория развертывания* — директория для файлов сайта относительно домашнего каталога владельца. Нельзя указать домашний каталог, каталог ~/.gitrepo и каталог другого репозитория. Если в репозитории есть файл index (для Node.js — package.json), панель удалит стандартную заглушку index.html.
  • Существующие файлы* — действия с файлами, которые уже есть в директории развертывания: 
    • Перезаписать существующие файлы — одноименные файлы заменятся файлами из репозитория, остальные останутся. Выберите этот вариант, если в директории есть нужные файлы, которых нет в репозитории.

    • Перезаписать и удалить лишние — одноименные файлы заменятся, остальные удалятся. Выберите этот вариант, если содержимое директории должно в точности повторять содержимое репозитория.

      Файлы, которых нет в репозитории, будут безвозвратно удалены.

    • Добавлять только новые — существующие файлы не изменятся, добавятся только отсутствующие. Выберите этот вариант, если нужно сохранить текущие версии файлов.

  • Автоматическая синхронизация — после каждого push файлы копируются в ispmanager. Для этого панель создает веб-хук.

    Как добавить веб-хук в Git-систему

    Git-система должна иметь доступ к панели по порту 1500. Веб-хук создается после сохранения формы.

    Скопируйте веб-хук в ispmanager: 

    1. Авторизуйтесь в панели под нужной учетной записью.
    2. Перейдите в раздел Сайты.
    3. В контекстном меню для нужного сайта выберите Git-репозитории.
    4. Выберите нужный репозиторий и на панели инструментов нажмите иконка "Изменить параметры Git-репозитория".
    5. Скопируйте URL веб-хука.

    Добавьте его в настройки репозитория:

    1. Авторизуйтесь на GitHub.
    2. Перейдите в нужный репозиторий.
    3. На панели инструментов нажмите иконка шестеренка Settings. 
    4. В меню слева выберите Webhooks.

    5. Нажмите Add webhook и заполните поля: 

      • Payload URL — вставьте скопированный веб-хук.
      • SSL verification — если для панели используется сертификат от Let's Encrypt или другого центра сертификации, оставьте опцию Enable SSL verification. Если самоподписанный — отметьте Disable.

      Остальные поля оставьте без изменений

    6. Нажмите Add webhook.
  • Автоматическое развертывание — после каждой синхронизации файлы публикуются на сайте.

  • Команды развертывания — собственный скрипт публикации. Поле доступно, если у владельца сайта включен shell. Без скрипта файлы копирует встроенная утилита rsync.

    Как написать свои команды развертывания

    Пример заготовки скрипта:

    set -e
rsync -a --exclude=.git "./" "/var/www/ПОЛЬЗОВАТЕЛЬ/data/www/САЙТ/ДИРЕКТОРИЯ_РАЗВЕРТЫВАНИЯ" #ispmgr-managed-publish
    • set -e прерывает скрипт на первой команде с ошибкой. Развертывание получает статус ошибки, а копирование не выполняется.

    • rsync копирует файлы из рабочей директории в директорию развертывания. Строка связана с полями Директория развертывания и Существующие файлы. Изменение значений в полях меняет команду, а изменение команды меняет поля.

      Если удалить строку с rsync, поля Директория развертывания и Существующие файлы исчезнут из формы, а перенос файлов придется прописать в скрипте вручную.

    Команды сборки, например npm ci или pip install, добавляйте до строки rsync. Тогда на сайт попадут и собранные файлы, и исходный код.

    Скрипт передается в stdin оболочки sh без временных файлов. Панель добавляет пути к нужной версии Node.js или Python в начало переменной PATH, поэтому node, npm и pip запускаются в правильных версиях. Для перезагрузки сайта доступны инструменты управления процессами, например pm2. Скрипт выполняется не дольше 30 минут. После этого развертывание получает статус ошибки, а в журнал добавляется запись Deploy timed out after 1800 seconds.

После сохранения формы ispmanager клонирует репозиторий и разворачивает файлы в директорию развертывания. Сразу после клонирования развертывание выполняется всегда, даже если вы не настраивали автоматизацию. Для нового сайта выпускается бесплатный сертификат Let's Encrypt. Если выпуск невозможен, устанавливается самоподписанный сертификат. Новый сайт появляется в списке со значком иконка "Git-репозиторий подключен".

Обновление сайта вручную

  1. Перейдите в раздел Сайты.
  2. В контекстном меню сайта нажмите Git-репозитории. 
  3. Выделите репозиторий в списке.

  4. На панели инструментов нажмите иконка "Получить обновления" Pull, чтобы получить изменения из удаленного репозитория.

    Pull перезаписывает изменения, внесенные в рабочую директорию на сервере ispmanager. Редактируйте проект только в удаленном репозитории.

  5. Нажмите иконка "Развернуть файлы в директорию сайта" Deploy, чтобы опубликовать их на сайте.

Просмотр истории коммитов

  1. Перейдите в раздел Сайты.
  2. В контекстном меню сайта нажмите Git-репозитории. 
  3. Выделите репозиторий в списке.
  4. На панели инструментов нажмите иконка "Журнал коммитов" Журнал коммитов. 

Журнал строится по рабочей копии и хранит 50 последних коммитов.

Поиск и устранение проблем

  1. Перейдите в раздел Сайты.
  2. В контекстном меню сайта нажмите Git-репозитории. 
  3. Выделите репозиторий в списке.
  4. На панели инструментов нажмите иконка "История развертывания репозитория" Журнал развертываний. 

В нем записаны ошибки синхронизации, клонирования и развертывания.

Типичные ошибки и способы их решения:

Запись в журналеПричинаРешение
Remote branch … not foundВ репозитории нет указанной веткиПроверьте поле Ветка в настройках репозитория
Authentication failedНеверные логин, пароль или токен, либо истек срок действия токенаПроверьте данные для доступа к репозиторию в настройках, при необходимости создайте новый токен в Git-системе
Permission denied (publickey)SSH-ключ не добавлен в репозиторийДобавьте SSH-ключ из ispmanager в настройки репозитория в Git-системе

Удаление репозитория

  1. Перейдите в раздел Сайты.
  2. В контекстном меню сайта нажмите Git-репозитории. 
  3. Выделите репозиторий в списке.

  4. На панели инструментов нажмите иконка "Удалить Git-репозиторий". 

    Вместе с репозиторием удаляются журнал развертываний и рабочая копия. Файлы в директории развертывания остаются.

При удалении сайта все его репозитории удаляются вместе с рабочими копиями.

Технические подробности для модуля Git

Рабочая директория: /var/www/ИМЯ_ПОЛЬЗОВАТЕЛЯ/data/.gitrepo/ID_РЕПОЗИТОРИЯ, где ID_РЕПОЗИТОРИЯ — идентификатор из таблицы gitrepo

Таблицы в базе данных панели: 

  • gitrepo — настройки, статусы, токен веб-хука
  • gitrepo_log — журнал развертываний

Удаление модуля Git

  1. Авторизуйтесь в панели под учетной записью уровня администратор или выше.
  2. Перейдите в раздел Конфигурация ПО.
  3. Выберите в списке Git.
  4. На панели инструментов нажмите иконка "Удалить ПО".

Утилита git и файлы клонированных сайтов останутся без изменений.

В этой статье