# Отладка прикладного решения

```{warning}
Работает только на Java 21.
```

Иногда программную ошибку не получается воспроизвести на тестовых стендах. В таких случаях, gs-ctk позволяет создать среду для отладки прикладного решения в условиях, максимально приближенных к тем, в которых работает основной кластер.

Для этого создается под, в котором стартует тот же сервер приложений, что и обычно, но с включенной подсистемой отладки Java. В поде также есть дополнительный сопровождающий контейнер со средой OpenVSCode Server, подключенной к данной подсистеме. Обычные пользователи не могут подключиться к данному поду без особой ссылки.

## Требования

- gs-ctk версии `>=5.1.4` (проверить командой: `cat ~/nscli/version.txt`)
- Минимальные ресурсы: 12 ГБ ОЗУ, 4 ядра CPU
- Настроенная работающая группа ресурсов с включенными книгами ресурсов `global_server_share` и `haproxy`
- Наличие в комплекте приложений архива `appsrc.zip`, содержащего исходные файлы проекта

## Подготовка исходного кода для отладки

Архив `appsrc.zip` должен быть собран из той же версии проекта, что и `applib.zip` в комплекте приложений.

Флаг `--build-appsrc` позволяет за один запуск gsf-cli собрать каталоги `applib` и `appsrc`. Флаг  
поддерживается только для SBT-проектов. В `project.yaml` параметр `isPublishSrcFolder` должен быть равен `true`  
или отсутствовать. По умолчанию публикация исходных артефактов включена.

### Локальная сборка

Из каталога gsf-cli выполните:

```bash
./manage.sh -p <имя_проекта> build --build-appsrc --skip-publication
```

В Windows используйте `manage.cmd` с теми же параметрами.

Команда выполняет чистую SBT-сборку, затем последовательно запускает `publishLibFolder` и `publishSrcFolder`.  
Флаг `--skip-publication` отключает загрузку в удалённый репозиторий, но не мешает созданию локальных артефактов.

Без `--publish-path` результат будет сохранён в каталогах:

- `workspace/sources/<имя_проекта>/application/build/publish/applib`;
- `workspace/sources/<имя_проекта>/application/build/publish/appsrc`.

gsf-cli проверяет, что оба набора JAR-файлов созданы. Если release уже отмечен как собранный, но локальные  
`applib` или `appsrc` отсутствуют или неполны, они будут пересобраны без повторной удалённой публикации.

### Сборка в CI/CD

Для сборки в заданный каталог укажите общий корень для `applib` и `appsrc`:

```bash
./manage.sh -p "$GSF_PROJECT_NAME" build \
  --build-appsrc \
  --skip-publication \
  --publish-path "$CI_PROJECT_DIR/publish"
```

В этом примере будут созданы `$CI_PROJECT_DIR/publish/applib` и `$CI_PROJECT_DIR/publish/appsrc`. Их можно сохранить как  
артефакты GitLab CI:

```yaml
artifacts:
  paths:
    - publish/applib/
    - publish/appsrc/
```

Не используйте один `--publish-path` вместе с `--all`: gsf-cli отклонит такой запуск, поскольку проекты могут  
перезаписать артефакты друг друга. Запускайте сборку отдельно с `-p` и уникальным корневым каталогом для каждого проекта.

### Локальная и удалённая публикация

`--publish-path` задаёт только локальный корневой каталог. Если не указывать `--skip-publication`, команда `build` также выполнит  
`sbt publish`. При включённом `isPublishSrcFolder` в Maven-репозиторий будут отправлены отдельные `*-sources.jar`, но не весь  
каталог `appsrc` или архив `appsrc.zip`.

gsf-cli создаёт каталоги с JAR-файлами, но не создаёт `applib.zip` и `appsrc.zip`. Архив `appsrc.zip` формируется при упаковке  
комплекта приложений средствами nscli.

Если первая release-сборка выполнялась с `--skip-publication`, а затем артефакты нужно отправить в Maven-репозиторий,  
выполните:

```bash
./manage.sh -p <имя_проекта> publish
```

### Ручной запуск SBT-задачи

Для старых версий gsf-cli или для диагностики можно по-прежнему запустить SBT-консоль активного проекта:

```bash
./links/active_project_sbt.sh
```

В Windows используйте `links\active_project_sbt.cmd`. В SBT-консоли выполните:

```text
publishSrcFolder
```

Исходные файлы будут опубликованы в каталоге `build/publish/appsrc` внутри исходного проекта (в рабочем каталоге gsf-cli это `workspace/sources/<имя_проекта>/application/build/publish/appsrc`). Добавьте этот каталог в корень комплекта приложений под именем `appsrc`. При упаковке комплекта средствами nscli будет сформирован архив `appsrc.zip` и рассчитаны его хеш-суммы.

## Инструкция по отладке

### Запуск отладчика

Администратор включает отладку при помощи команды nscli:

```bash
~/nscli $ ./cloud_debugger.sh --namespace gs-ctk start
```

```text
Укажите группу ресурсов:gs-cluster-1
Выберите книгу ресурсов, которую необходимо взять за основу облачного отладчика:global-server-share
Укажите название для отладчика:debugger-5edafd63
Точка во времени в формате эпохи Unix, до которой будет доступен отладчик (или укажите от текущего момента указав в качестве значения
"+N", где N - время в секундах):+3600
Облачный отладчик будет доступен до 03:14:08 19.01.2038
Ожидаем готовности облачного отладчика...
Ожидаем готовности облачного отладчика...
Ожидаем готовности облачного отладчика...
Облачный отладчик готов к использованию!

Для доступа к отладчику перейдите по ссылке:
(http://example.ru)/debugger/open/gs-cluster-1-debugger-1b0e4084?debugger%2Fvscode%2F%3Ftkn%3Dba0211cf-cd8a-4ba5-b2a2-a5d1791e587b%26folder%3D%2Fuser%2Fapplication

Чтобы подключиться к серверу приложений, связанному с отладчиком, перейдите по ссылке:
(http://example.ru)/debugger/open/gs-cluster-1-debugger-1b0e4084?login%2Flogin.html
```

Подстроку `(https://example.ru)` надо подменить на имя хоста, к которому обращается пользователь для подключения к HAProxy. Например:

```text
https://globalerp.mycompany.ru/debugger/open/gs-cluster-1-debugger-1b0e4084?debugger%2Fvscode%2F%3Ftkn%3Dba0211cf-cd8a-4ba5-b2a2-a5d1791e587b%26folder%3D%2Fuser%2Fapplication
```

### Управление отладчиками

Для просмотра списка активных отладчиков:

```bash
./cloud_debugger.sh --namespace gs-ctk list
```

Для удаления отладчика:

```bash
./cloud_debugger.sh delete --namespace gs-ctk --group my-group --book debugger-mydebugger
```

### Подключение к отладчику

1. Администратор передает ссылки разработчикам (или другим лицам, проводящим отладку).
2. Разработчик переходит в отладчик и на сервер приложений по ссылкам.
  **Важно:** Используйте HTTPS для подключения. При проблемах с аутентификацией (циклическая переадресация) очистите cookies браузера.
    ![Внешний вид облачного отладчика](img/vscode-preview.png)

### Настройка Visual Studio Code

В поде облачного отладчика уже установлены OpenVSCode Server и необходимые расширения Java, Scala и Metals. Дополнительно устанавливать расширения не требуется.

1. Подтвердите, что каталог `/user/application` является доверенным, и откройте вкладку Metals на боковой панели.

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

    ![Дождитесь завершения индексации](img/vscode-indexing.png)

    Если индексация не началась, или после ее завершения модули не появились, нажмите "Import build" в секции "Build Commands" вкладки Metals.

    ![Библиотеки и модули успешно подгрузились](img/vscode-packages.png)

3. На вкладке Metals выполните команду "Run doctor". В отчёте должен присутствовать build target `application` с отметкой в столбце "Debugging".

4. В разделе "Packages" → "Libraries" проверьте, что доступны модули проекта и внешние зависимости.

5. Откройте нужные модули или библиотеки и установите точки останова, щёлкнув слева от номера нужной строки.

6. Перейдите на вкладку "Run and Debug" боковой панели, выберите конфигурацию `Global Debug` и нажмите "Start Debugging".

    ![Кнопка запуска отладки](img/vscode-debug.png)

Отладчик включен и подключен к серверу приложений, интерфейс которого доступен через вторую ссылку. Лог сервера приложений доступен по адресу `/user/application/globalserver.log`.

```{note}
При запуске облачного отладчика gs-ctk автоматически создаёт отдельный под, запускает Global Server с включённой удалённой отладкой и добавляет в Visual Studio Code готовую конфигурацию `Global Debug`. Изменять `start.sh` сервера приложений или создавать конфигурацию подключения вручную не требуется.
```

## Устранение проблем

### Проблема с аутентификацией

Если после успешной авторизации происходит переадресация на страницу входа:

- Очистите cookies браузера для домена отладчика
- Используйте для подключения только протокол HTTPS

## Безопасность

В ссылку для отладчика вписан токен для подключения, который используется для авторизации в OpenVSCode Server. Следовательно, без этой ссылки подключиться к отладчику невозможно.

В будущих версиях, способ авторизации может измениться.

OpenVSCode Server работает в отдельном контейнере от имени непривилегированного пользователя, не имеет прямого доступа к секретам и файловым системам других контейнеров.

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