Версия: v2 (текущая)

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

Кратко. PanDev Metrics on-prem поставляется в виде архива дистрибутива, в котором есть готовый к запуску стек Docker Compose и встроенный Helm-чарт. Вы настраиваете один файл .env, а затем выполняете либо docker compose up -d, либо helm install. Стек состоит из трёх компонентов — backend (:8080), workspace UI (:8090) и PostgreSQL 16, — причём PostgreSQL входит в дистрибутив. Аудитория: администратор.

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

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

Путь Docker Compose — один хост с 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), а порты контейнеров держите в приватной сети или за firewall. Понадобится доступный hostname и TLS-сертификат (подойдёт и самоподписанный с отключённой клиентской валидацией).
Взаимная доступность с интеграциями. Если вы подключаете облачные Git-провайдеры или таск-трекеры, публичный URL backend должен быть доступен и им — чтобы доходили вебхуки (синхронизация в реальном времени). Связь с интеграциями двусторонняя — см. Сеть и порты.

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

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

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 — Изучите 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:5.8.0
    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:2.8.0
    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 редактировать не нужно.

Шаг 2 — Настройте файл `.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 — например:

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.

Тест только на той же машине: подойдёт http://localhost:8080 (значение по умолчанию).
Реальное развёртывание: укажите публичный URL backend, например https://metrics.example.com (ваш reverse proxy) или http://<host-ip>:8080. Внутреннее имя вроде http://pandev-metrics-server:8080 в браузере не разрешится. :::

warning

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

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

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

docker-compose.yml
    image: pandevofficial/pandev-metrics:5.8.0-arm
    # ...
    image: pandevofficial/pandev-metrics-backoffice:2.8.0-arm

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

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

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, а затем стартовый баннер приложения.

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

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

terminal
docker compose ps

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

Затем откройте workspace UI в браузере по адресу http://<host>:8090. Должен появиться экран входа PanDev Metrics, и он должен без ошибок обращаться к API на порту 8080. Первого администратора создаёте в процессе первого входа.

примечание

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

Шаг 6 — (рекомендуется) Поставьте reverse proxy перед стеком

Для всего, кроме локального теста, терминируйте TLS на reverse proxy и маршрутизируйте два имени: 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;
  }
}

# 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, TLS и firewall см. в Сети и портах.

Развёртывание через 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`	`5.8.0` / `2.8.0`	Версии образов; для arm64-узлов добавляйте `-arm`
`postgresql.enabled`	`true`	Использовать встроенный StatefulSet PostgreSQL
`postgresql.auth.password`	`""`	Пароль встроенной БД (генерируется, если оставить пустым)
`postgresql.auth.username` / `.database`	`postgres` / `pandev_metrics_db`	Пользователь и имя базы встроенного PostgreSQL
`postgresql.primary.persistence.enabled`	`false`	Персистентное хранилище БД — см. предупреждение ниже
`externalDatabase.*`	—	Используется при `postgresql.enabled=false`

:::danger Включите персистентность для продакшена По умолчанию postgresql.primary.persistence.enabled=false, и БД работает поверх emptyDir — все данные теряются при перезапуске пода. Для любой реальной установки включите PersistentVolumeClaim:

values.yaml
postgresql:
  auth:
    password: "<STRONG_DB_PASSWORD>"
  primary:
    persistence:
      enabled: true
      size: 20Gi
      # storageClass: "your-storage-class"

:::

Шаг 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 в браузере и пройдите первый вход.

Обновления

Путь обновления одинаков для обоих развёртываний: поднимаете теги образов и даёте Flyway мигрировать схему на старте. Сначала снимите бэкап (см. ниже).

Docker Compose — измените теги образов в docker-compose.yml, затем docker compose pull && docker compose up -d.
Helm — helm upgrade pandev-metrics ./helm-chart -n metrics -f values.yaml с новыми server.image.tag / workspace.image.tag.

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

Бэкапы и 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: данные БД пропадают после перезапуска пода

Персистентность отключена по умолчанию (emptyDir). Задайте postgresql.primary.persistence.enabled=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 (...:5.8.0-arm, ...:2.8.0-arm) — это нативные arm64-сборки. Теги по умолчанию рассчитаны на x86_64.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Шаг 5 — Проверьте​

Шаг 6 — (рекомендуется) Поставьте reverse proxy перед стеком​

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

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

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

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

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

Обновления​

Бэкапы и disaster recovery​

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

FAQ​

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

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

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

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

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

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

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