Установка PanDev Metrics on-prem

Кратко. PanDev Metrics on-prem поставляется в виде архива дистрибутива, в котором есть готовый к запуску стек Docker Compose и встроенный Helm-чарт. Для production-установки через Docker Compose сначала создайте Linux VM, опубликуйте наружу только Nginx / reverse proxy на 443, затем настройте .env и запустите стек. Для Helm настройте values.yaml и Ingress через встроенный чарт. Аудитория: администратор.

Что понадобится

Выберите один путь развёртывания и подготовьте его предпосылки плюс архив дистрибутива:

• Путь Docker Compose — одна Linux VM или хост с Docker Engine ≥ 20.10 и Docker Compose ≥ v2.0 (рекомендуется v2.20+).
• Путь Helm — кластер Kubernetes 1.28+ с Helm 3 и настроенным на него kubectl.

В обоих случаях также нужны:

• Архив дистрибутива PanDev Metrics от вашего менеджера.
• Хост x86_64 (теги образов по умолчанию) или arm64 (теги -arm) — базовый набор CPU-инструкций см. в системных требованиях.
• Исходящий HTTPS до вашего Git-провайдера и таск-трекера — egress минимальный, но отключить нельзя.
• Reverse proxy для установки. Не выставляйте порты стека (8080/8090) напрямую пользователям — публикуйте наружу только reverse proxy по TLS (443), а порты контейнеров держите за ним. Понадобятся доступные hostname UI/API и TLS-сертификат, которому доверяют браузеры и IDE-плагины.
• Взаимная доступность с интеграциями. Если вы подключаете облачные Git-провайдеры или таск-трекеры, публичный URL backend должен быть доступен и им — чтобы доходили вебхуки (синхронизация в реальном времени). Связь с интеграциями двусторонняя — см. Сеть и порты.

Для Docker Compose подготовьте VM и reverse proxy до редактирования .env. Workspace читает API_BASE_URL при старте и зашивает это значение в UI, который работает в браузере, поэтому смена публичного имени API позже потребует пересоздать workspace-контейнер.

Что внутри архива

Архив дистрибутива выдаёт ваш менеджер. Распакуйте его в рабочую директорию:

terminal

sudo mkdir -p /opt/pandev
sudo chown "$USER":"$USER" /opt/pandev
cd /opt/pandev
unzip /tmp/pandev-metrics-distribution.zip -d .

В архиве — два самодостаточных варианта развёртывания плюс конфигурация:

.
├── docker-compose/
│   ├── .env                 # файл, который вы редактируете
│   └── docker-compose.yml   # server + workspace + PostgreSQL
└── helm-chart/
    ├── Chart.yaml
    ├── values.yaml          # все параметры Helm, с комментариями
    ├── README.md
    └── templates/

PostgreSQL устанавливать или готовить отдельно не нужно — он входит и в Compose-стек, и в Helm-чарт. Выберите один путь развёртывания:

• Docker Compose — один хост с Docker. Самый простой путь и вариант по умолчанию для большинства установок.
• Helm / Kubernetes — существующий кластер Kubernetes (1.28+).

warning

PanDev Metrics on-prem — установка на одну организацию. Не закладывайтесь на multi-tenant разделение: это возможно только в Cloud. Air-gapped развёртывания не поддерживаются: backend-у нужен минимальный исходящий HTTPS до вашего Git-провайдера и таск-трекера.

Три компонента

Оба пути развёртывания запускают одни и те же три образа:

Компонент	Образ	Порт	Роль
Server (backend)	pandevofficial/pandev-metrics	8080	REST API для UI и IDE-плагинов; на старте прогоняет Flyway-миграции
Workspace (frontend)	pandevofficial/pandev-metrics-backoffice	8090 → контейнерный 80	Веб-интерфейс; статический React-бандл за Nginx
PostgreSQL	postgres:16 (Compose) / public.ecr.aws/bitnami/postgresql:16 (Helm)	5432	Хранилище всех персистентных данных

Встроенный PostgreSQL — версии 16; backend также совместим с PostgreSQL 17, если вы используете внешнюю или managed-базу.

Backend — это нативный образ, собранный через GraalVM, поэтому он публикуется отдельно под каждую архитектуру CPU. Теги по умолчанию рассчитаны на x86_64; образы с суффиксом -arm — на arm64 (включая Apple Silicon). Выбирайте тег под вашу архитектуру — точный набор требуемых CPU-инструкций см. в системных требованиях.

---

Развёртывание через Docker Compose

Шаг 1 — Подготовьте VM и reverse proxy периметр

Сначала создайте application VM. Возьмите размер из системных требований, используйте поддерживаемый Linux-дистрибутив и убедитесь, что гипервизор пробрасывает нужные CPU-инструкции, если VM работает на x86_64.

Перед распаковкой архива дистрибутива:

• Назначьте VM стабильный приватный IP-адрес.
• Создайте DNS-записи для публичных имён, которые будете публиковать: например, app.example.com для workspace и metrics.example.com для backend API.
• Убедитесь, что эти имена разрешаются из браузеров пользователей, хостов IDE-плагинов и подключённых провайдеров, которые доставляют вебхуки. Облачные Git-провайдеры и таск-трекеры смогут доставлять вебхуки только если имя backend API доступно с их стороны.
• Установите Docker Engine, Docker Compose, unzip и Nginx.
• Откройте входящий 443 на Nginx. Не публикуйте 8080, 8090, 5432 и 9090 как пользовательские endpoints.
• Установите TLS-сертификат, который соответствует hostname UI и API.

Если Nginx работает на той же VM, что и Docker Compose, он должен проксировать workspace на http://127.0.0.1:8090, а backend — на http://127.0.0.1:8080. Так публичной поверхностью остаётся только 443, но локальные проверки и логи на VM по-прежнему доступны.

Шаг 2 — Изучите Compose-файл

Перейдите в каталог Compose и посмотрите, что будет запущено:

terminal

cd /opt/pandev/docker-compose

docker-compose.yml описывает три сервиса в приватной bridge-сети. Server берёт строку подключения к БД из переменных POSTGRES_*, workspace — из API_BASE_URL, а PostgreSQL хранит данные в именованном томе (postgres-data), поэтому они переживают перезапуски:

docker-compose.yml (фрагмент)

services:
  pandev-metrics-server:
    image: pandevofficial/pandev-metrics:<version>   # точный тег зафиксирован в поставляемом файле
    ports: ["8080:8080"]
    environment:
      DB_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB}
      DB_USERNAME: ${POSTGRES_USER}
      DB_PASSWORD: ${POSTGRES_PASSWORD}
      DB_SCHEMA: public

  pandev-metrics-workspace:
    image: pandevofficial/pandev-metrics-backoffice:<version>
    ports: ["8090:80"]
    environment:
      API_BASE_URL: ${API_BASE_URL}

  postgres:
    image: postgres:16
    ports: ["5432:5432"]
    volumes: [postgres-data:/var/lib/postgresql/data]

Обратите внимание: DB_URL, DB_USERNAME и DB_PASSWORD сервера собираются автоматически из значений POSTGRES_*, которые вы зададите в .env. Для стандартной установки docker-compose.yml редактировать не нужно.

Шаг 3 — Настройте файл .env

В архиве уже есть готовый файл .env в каталоге docker-compose/. В поставке он содержит значения для ознакомления — это полный набор переменных, больше настраивать нечего:

docker-compose/.env (как в поставке)

# --- PostgreSQL ---
POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres

# --- Frontend ---
API_BASE_URL=http://localhost:8080

Для установки поменяйте хотя бы пароль БД и публичный URL API. Используйте API hostname, который будет публиковать Nginx, а не имя Docker-сервиса:

docker-compose/.env (отредактировано для реальной установки)

POSTGRES_DB=pandev_metrics
POSTGRES_USER=pandev
POSTGRES_PASSWORD=<STRONG_DB_PASSWORD>
API_BASE_URL=https://metrics.example.com

Переменная	Назначение	Примечания
POSTGRES_DB	Имя базы, создаваемой при первом старте	Любой допустимый идентификатор
POSTGRES_USER	Пользователь БД, под которым подключается backend	Создаётся автоматически внутри контейнера postgres
POSTGRES_PASSWORD	Пароль этого пользователя	Задайте надёжное значение; это единственный секрет БД
API_BASE_URL	URL backend, по которому к API обращается браузер	См. примечание ниже — именно в этой переменной чаще всего ошибаются

:::info Про API_BASE_URL Workspace — это SPA, которое работает в браузере пользователя. API_BASE_URL зашивается в UI как адрес, по которому браузер делает каждый API-запрос, — поэтому он должен быть доступен с машины пользователя, а не изнутри Docker.

Укажите публичный URL backend, например https://metrics.example.com (ваш reverse proxy). Имя Docker-сервиса вроде http://pandev-metrics-server:8080 в браузере не разрешится. :::

warning

Относитесь к .env как к секрету: chmod 600 .env и не коммитьте в репозиторий. Значения по умолчанию (postgres/postgres/postgres) не являются production-значениями — всегда меняйте POSTGRES_PASSWORD перед тем, как открыть установку наружу.

Шаг 4 — (только arm64) переключитесь на образы -arm

Если ваш хост — arm64 (например, Apple Silicon), отредактируйте docker-compose.yml и выберите теги -arm, которые закомментированы рядом с тегами x86_64 по умолчанию:

docker-compose.yml

    image: pandevofficial/pandev-metrics:<version>-arm
    # ...
    image: pandevofficial/pandev-metrics-backoffice:<version>-arm

На хостах x86_64 оставьте теги по умолчанию как есть.

Шаг 5 — Скачайте образы и поднимите стек

terminal

docker compose pull
docker compose up -d

При первом старте backend прогоняет Flyway-миграции против пустой базы, затем запускается. Подождите 1–3 минуты до готовности. Логи смотрите так:

terminal

docker compose logs -f pandev-metrics-server

Вы увидите строки org.flywaydb.core.internal.command.DbMigrate, а затем стартовый баннер приложения.

Шаг 6 — Направьте публичные имена через Nginx

Терминируйте TLS на Nginx и маршрутизируйте два имени: UI — на workspace (:8090), API — на backend (:8080). Значение API_BASE_URL должно совпадать с публичным именем API из этой конфигурации.

/etc/nginx/conf.d/pandev.conf

# Workspace UI
server {
  listen 443 ssl http2;
  server_name app.example.com;
  ssl_certificate     /etc/ssl/certs/pandev.crt;
  ssl_certificate_key /etc/ssl/private/pandev.key;
  location / {
    proxy_pass http://127.0.0.1:8090;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
  }
}

# Backend API
server {
  listen 443 ssl http2;
  server_name metrics.example.com;   # совпадает с API_BASE_URL
  ssl_certificate     /etc/ssl/certs/pandev.crt;
  ssl_certificate_key /etc/ssl/private/pandev.key;
  location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
  }
}

Проверьте и перезагрузите Nginx после сохранения файла:

terminal

sudo nginx -t
sudo systemctl reload nginx

Полную справку по proxy, TLS и firewall см. в Сети и портах.

Шаг 7 — Проверьте

Убедитесь, что все три контейнера в порядке. У PostgreSQL есть встроенный health-check; остальные два должны быть Up:

terminal

docker compose ps

NAME                       STATUS
pandev-metrics-server      Up
pandev-metrics-workspace   Up
postgres                   Up (healthy)

Откройте workspace UI через Nginx, например https://app.example.com. Должен появиться экран входа PanDev Metrics, а браузер должен без сетевых ошибок обращаться к API по https://metrics.example.com.

Первого администратора создаёте в процессе лицензирования и первого входа.

примечание

Порты 8080 (API backend) и 8090 (workspace UI) публикуются на хост, чтобы Nginx мог проксировать к ним локально. Им не нужно быть доступными из публичной сети. Spring-actuator (health/metrics) слушает порт 9090 внутри контейнера и Compose-файлом наружу не публикуется — судите о состоянии backend по docker compose ps и логам, а не по внешнему обращению к :9090. Поставляемый Compose-файл также публикует PostgreSQL на 5432; забиндите его на 127.0.0.1 или закройте на firewall — backend ходит в базу по Docker-сети, поэтому выставлять 5432 наружу не нужно.

---

Развёртывание через Helm

Встроенный чарт в helm-chart/ разворачивает те же три компонента в Kubernetes 1.28+ (Helm 3). PostgreSQL входит как StatefulSet, либо вы можете направить чарт на внешнюю базу.

Шаг 1 — Установка

Из распакованного архива установите чарт и передайте публичные URL для API и UI. Чарт использует serverUrl и workspaceUrl, чтобы настроить хосты Ingress и автоматически подставить API_BASE_URL во workspace:

terminal

cd /opt/pandev

helm install pandev-metrics ./helm-chart \
  --namespace metrics --create-namespace \
  --set serverUrl=https://metrics.example.com \
  --set workspaceUrl=https://app.example.com \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set postgresql.auth.password=<STRONG_DB_PASSWORD>

Для всего, кроме быстрой пробы, предпочитайте файл values.yaml длинным цепочкам --set.

Шаг 2 — Ключевые параметры

Это параметры, которые трогает большинство установок. Полный список с комментариями выводит helm show values ./helm-chart — там же документирован каждый параметр, как и в helm-chart/README.md из архива.

Параметр	По умолчанию	Назначение
serverUrl	""	Публичный URL backend; одновременно становится API_BASE_URL для workspace
workspaceUrl	""	Публичный URL UI
ingress.enabled / ingress.className	false / ""	Создать Ingress и выбрать контроллер (например, nginx)
server.image.tag / workspace.image.tag	задаётся в values.yaml для каждого релиза	Версии образов; для arm64-узлов добавляйте -arm
postgresql.enabled	true	Использовать встроенный StatefulSet PostgreSQL
postgresql.auth.password	""	Пароль встроенной БД (генерируется, если оставить пустым)
postgresql.auth.username / .database	postgres / pandev_metrics_db	Пользователь и имя базы встроенного PostgreSQL
postgresql.primary.persistence.enabled / .size	true / 100Gi	Персистентный PVC для БД — включён по умолчанию; см. примечание ниже
externalDatabase.*	—	Используется при postgresql.enabled=false

:::warning Персистентность включена по умолчанию — убедитесь, что PVC привяжется Поставляемый чарт идёт с postgresql.primary.persistence.enabled=true и PVC на 100Gi, поэтому данные БД и так переживают перезапуск пода. Тонкость — в StorageClass: если в кластере нет дефолтного StorageClass и вы его не задали, PVC останется в статусе Pending, и под PostgreSQL не стартует. В случае сомнений укажите его явно:

values.yaml

postgresql:
  auth:
    password: "<STRONG_DB_PASSWORD>"
  primary:
    persistence:
      enabled: true                       # по умолчанию
      size: 100Gi                         # по умолчанию; совпадает с размером диска из системных требований
      storageClass: "your-storage-class"  # задайте, если в кластере нет дефолтного StorageClass

Ставьте enabled: false только для одноразового ознакомления — это переводит PostgreSQL на emptyDir, и все данные теряются при перезапуске пода. :::

Шаг 3 — (опционально) Внешняя база данных

Чтобы работать с managed- или внешним PostgreSQL вместо встроенного, отключите встроенную базу и заполните externalDatabase:

values.yaml

postgresql:
  enabled: false

externalDatabase:
  host: "db.internal"
  port: 5432
  user: "pandev"
  password: "<STRONG_DB_PASSWORD>"
  database: "pandev_metrics_db"

Шаг 4 — Проверьте

terminal

kubectl get pods -n metrics
helm status pandev-metrics -n metrics

Поды переходят в Ready по мере прохождения проб — backend-под на management-порту (9090), поды workspace и PostgreSQL по своим проверкам. Итоговые URL печатает Helm в release notes. Затем откройте workspaceUrl в браузере и пройдите лицензирование и первый вход.

---

Обновления и релизы

PanDev Metrics регулярно выпускает новые on-prem-сборки. Обновление одинаково для обоих развёртываний: поднимаете теги образов и даёте Flyway мигрировать схему на старте. Сначала снимите бэкап (см. Бэкапы и disaster recovery).

Как узнать текущую версию

В Docker Compose версия — это теги запущенных образов:

terminal

docker compose images

В Kubernetes:

terminal

helm list -n metrics
kubectl get deploy -n metrics -o jsonpath="{.items[*].spec.template.spec.containers[*].image}"

Версию также видно в футере веб-интерфейса после входа под админом.

Где смотреть release notes

Подробный changelog по каждому релизу — с версиями компонентов, версиями плагинов и ссылками на сборки — лежит в отдельном разделе, а не здесь:

• Текущий релиз — последняя версия с полными notes
• Все релизы — полный архив

Каждая запись содержит версии бэкенда (pandev-metrics) и workspace (pandev-metrics-backoffice) и их Docker-теги, версии плагинов IDE / CLI / браузерных расширений, а также bug fixes и новые фичи.

Обновление через Docker Compose

1. Прочитайте release notes для целевой версии.
2. Сделайте бэкап PostgreSQL через pg_dump (см. Бэкапы и disaster recovery).
3. Обновите image-теги в docker-compose.yml и для server, и для workspace (на хостах arm64 используйте теги -arm):

docker-compose.yml

services:
  pandev-metrics-server:
    image: pandevofficial/pandev-metrics:<НОВАЯ_ВЕРСИЯ_SERVER>
  pandev-metrics-workspace:
    image: pandevofficial/pandev-metrics-backoffice:<НОВАЯ_ВЕРСИЯ_WORKSPACE>

4. Подтяните образы и перезапустите:

terminal

docker compose pull
docker compose up -d

5. Подтвердите новые теги через docker compose images и что футер UI показывает новую версию.

Обновление через Helm

1. Сделайте бэкап PostgreSQL.
2. Обновите image-теги в values.yaml:

values.yaml

server:
  image:
    tag: <НОВАЯ_ВЕРСИЯ_SERVER>
workspace:
  image:
    tag: <НОВАЯ_ВЕРСИЯ_WORKSPACE>

3. Примените, используя чарт из распакованного архива:

terminal

helm upgrade pandev-metrics ./helm-chart -n metrics -f values.yaml

4. Дождитесь раскатки:

terminal

kubectl rollout status deployment/pandev-metrics-server -n metrics

Flyway применяет все pending-миграции автоматически на старте; вручную миграции вы не запускаете.

Совместимость версий

Обновление идёт только вперёд: ставите новую сборку, схема мигрирует на месте, и всё работает. Downgrade после применения миграций не поддерживается — если нужно откатиться, восстанавливайте бэкап. Плагины (IDE, browser, CLI) совместимы в пределах мажорной версии — обновляйте их в удобном темпе.

Бэкапы и disaster recovery

Для бэкапов достаточно регулярного pg_dump базы PanDev Metrics — continuous archiving не обязательно.

terminal — встроенный PostgreSQL (Compose)

docker compose exec postgres \
  sh -c 'pg_dump -Fc -U "$POSTGRES_USER" "$POSTGRES_DB"' > pandev_metrics_$(date +%F).dump

Переменные раскрываются внутри контейнера postgres (где их задаёт Compose), поэтому кавычки важны — запуск pg_dump -U "$POSTGRES_USER" напрямую с хоста подставил бы пустые значения.

Для внешней базы выполняйте pg_dump с хоста, который до неё дотягивается. Для восстановления используйте pg_restore, затем поднимите стек — миграции выровняются автоматически на следующем старте.

Решение проблем

Backend падает с FATAL: password authentication failed

POSTGRES_PASSWORD изменили уже после того, как том базы был инициализирован. PostgreSQL задаёт пароль только при первом старте. Либо верните пароль к исходному значению, либо сбросьте базу: docker compose down -v (это удалит том postgres-data и все данные) и docker compose up -d.

UI загружается, но все API-запросы падают (пустые дашборды, сетевые ошибки)

API_BASE_URL недоступен из браузера. Это должен быть публичный адрес backend, а не имя Docker-сервиса. Исправьте в .env и пересоздайте workspace: docker compose up -d --force-recreate pandev-metrics-workspace.

Контейнер backend сразу завершается с Illegal instruction (часто на VM)

Backend — это нативный образ GraalVM, ему нужен базовый набор x86_64-инструкций (AVX2, FMA, BMI2, …). Обычная причина — гипервизор маскирует CPU-фичи хоста. Пробросьте CPU хоста в VM — см. системные требования → виртуализация. На хостах arm64 используйте теги образов -arm.

Helm: под PostgreSQL застрял в статусе Pending

PVC базы не может привязаться — обычно потому, что в кластере нет дефолтного StorageClass. Посмотрите доступные через kubectl get storageclass, затем задайте postgresql.primary.persistence.storageClass одним из них и выполните helm upgrade. См. примечание о персистентности выше.

Helm: данные БД пропадают после перезапуска пода

Персистентность включена по умолчанию (PVC на 100Gi), поэтому такое случается, только если её явно отключили — postgresql.primary.persistence.enabled=false переводит PostgreSQL на emptyDir. Верните true (с size и, при необходимости, storageClass), затем выполните helm upgrade.

FAQ

Нужно ли ставить PostgreSQL самому?

Нет. PostgreSQL входит в дистрибутив — как контейнер в Docker Compose и как StatefulSet в Helm-чарте. Внешний PostgreSQL вы подключаете, только если осознанно выбираете postgresql.enabled=false (Helm) и указываете на свой инстанс.

Нужно ли создавать таблицы вручную?

Нет. Backend сам прогоняет Flyway-миграции при первом запуске и при каждом обновлении.

Работает ли PanDev Metrics на ARM / Apple Silicon?

Да. Используйте теги образов с суффиксом -arm (...:<version>-arm) — это нативные arm64-сборки. Теги по умолчанию рассчитаны на x86_64.

Можно ли отключить исходящий сетевой доступ?

Нет. PanDev Metrics нужен минимальный исходящий HTTPS до Git-провайдера и таск-трекера. Egress минимальный, но отключить нельзя, а air-gapped развёртывания не поддерживаются.

Какие версии Kubernetes поддерживаются?

Kubernetes 1.28+ с Helm 3. Чарт и Compose-стек имеют одинаковую форму конфигурации.

Как часто выходят релизы on-prem?

PanDev Metrics регулярно выпускает обновления бэкенда и плагинов. Жёсткой каденции нет — minor-версии выходят раз в несколько недель, патчи по мере необходимости. Темп лучше смотреть в Архиве релизов.

Нужно ли обновлять плагины вместе с бэкендом?

Не всегда. Плагины совместимы по версиям — старые плагины продолжают работать с более новым бэкендом в рамках одного мажора. Чтобы получить новые фичи (например, учёт AI-активности в CLI), обновите плагин до версии, указанной в release notes.

Можно ли пропускать версии при обновлении?

Да. Миграции выстраиваются в цепочку, поэтому при переходе с 4.5.x сразу на 4.7.2 отработают все промежуточные миграции по порядку. Сделайте бэкап и прочитайте notes по всем пропущенным версиям, чтобы не пропустить breaking changes.

Как откатить неудачный апгрейд?

Остановите новые контейнеры, восстановите PostgreSQL из дампа, который сделали перед обновлением, и запустите предыдущие image-теги. In-place downgrade не поддерживается — миграции схемы идут только вперёд.

Где скачать сборки плагинов?

Прямые ссылки на JetBrains, VS Code и Xcode-сборки публикуются в каждой записи релиза — см. Текущий релиз. Если рабочие станции разработчиков ходят через ограниченный egress и не могут достучаться до cdn.pandev.io, разместите артефакты на внутреннем зеркале.

Дальнейшие шаги

• Лицензирование и первый вход — активация лицензии и создание начального администратора
• LDAP-интеграция — подключение корпоративного каталога для SSO
• Сеть и порты — финализация reverse proxy и firewall

Связанные материалы

• Reference: Системные требования
• Концепция: Архитектура on-prem