Установка на ВМ (systemd)

Запустите сервисы control plane Planeon как systemd-юниты на Linux-хосте — вместо контейнеров, которые использует установка через Docker Compose. Этот путь использует те же артефакты релиза, те же переменные planeon.env и те же гарантии порядка операций — только упакованные как бинарники и Node.js-бандл под управлением systemd, а не образы контейнеров под управлением Compose.

Запланировано на релиз после 1.0

Автономные релизные бинарники — и хост артефактов downloads.planeon.io, на котором они должны публиковаться, — не входят в релиз v1.0.0; они запланированы на релиз после v1.0.0. Поддерживаемый путь установки для v1.0.0 — Docker Compose. Всё ниже (структура артефактов, systemd-юниты) описывает задуманный дизайн, чтобы вы могли планировать заранее; относитесь к этому как к предварительному, пока этот более поздний релиз не выйдет.

Предварительные требования

• Linux x86_64-хост с systemd.
• PostgreSQL 16 или новее и Redis 7 или новее, доступные с этого хоста — на этом же хосте, на другом хосте или как управляемый сервис. Ни один из них не устанавливается этим руководством.
• Node.js 22 или новее — веб-консоль — единственный компонент Planeon, который поставляется как Node.js-бандл, а не как нативный бинарник, и для его запуска на хосте нужен установленный рантайм Node.js.
• Docker или Podman — нужен только для запуска guacd (см. guacd ниже); каждый другой сервис Planeon в этом руководстве — нативный бинарник под прямым управлением systemd, без контейнерного рантайма.
• DNS-имя, обратный прокси с терминацией TLS перед веб-консолью, API и gateway, и уже настроенный OIDC-провайдер идентификации с созданным для Planeon приложением — те же три предварительных требования, что и у установки через Docker Compose, и по тем же причинам.
• Доступ к организации planeon на Docker Hub (или к её зеркалу в приватном registry) — guacd в этом варианте установки по-прежнему распространяется как образ контейнера.

Если вы ещё не сделали этого, перед тем как продолжить, прочитайте раздел Требования — там описан размер управляющего контура, поддержка браузеров и поддержка ОС шаблонов.

Скачайте артефакты релиза

Каждый сервис Planeon публикуется отдельным архивом linux_amd64, плюс Node.js-бандл для веб-консоли:

Компонент	Артефакт
api	planeon-api_linux_amd64.tar.gz
worker	planeon-worker_linux_amd64.tar.gz
gateway	planeon-gateway_linux_amd64.tar.gz
migrate CLI	planeon-migrate_linux_amd64.tar.gz
web	planeon-web_node.tar.gz

curl -fsSLO https://downloads.planeon.io/v1.0.0/planeon-api_linux_amd64.tar.gz
curl -fsSLO https://downloads.planeon.io/v1.0.0/planeon-worker_linux_amd64.tar.gz
curl -fsSLO https://downloads.planeon.io/v1.0.0/planeon-gateway_linux_amd64.tar.gz
curl -fsSLO https://downloads.planeon.io/v1.0.0/planeon-migrate_linux_amd64.tar.gz
curl -fsSLO https://downloads.planeon.io/v1.0.0/planeon-web_node.tar.gz

Точный набор артефактов — имена, контрольные суммы, подписи — определяется релизным конвейером; имена выше следуют шаблону, который публикует релиз v1.0.0.

Структура установки и конфигурация

Создайте отдельного системного пользователя и каталог для каждого компонента:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin planeon
sudo mkdir -p /opt/planeon/{api,worker,gateway,web,migrate} /etc/planeon

Распакуйте каждый артефакт в свой каталог и передайте дерево пользователю planeon:

sudo tar -xzf planeon-api_linux_amd64.tar.gz     -C /opt/planeon/api
sudo tar -xzf planeon-worker_linux_amd64.tar.gz  -C /opt/planeon/worker
sudo tar -xzf planeon-gateway_linux_amd64.tar.gz -C /opt/planeon/gateway
sudo tar -xzf planeon-migrate_linux_amd64.tar.gz -C /opt/planeon/migrate
sudo tar -xzf planeon-web_node.tar.gz            -C /opt/planeon/web
sudo chown -R planeon:planeon /opt/planeon

В результате получится такая структура:

/opt/planeon/
├── api/planeon-api
├── worker/planeon-worker
├── gateway/planeon-gateway
├── migrate/planeon-migrate
└── web/            # Node.js-бандл: server.js и сопутствующие файлы

Конфигурация хранится в одном файле, /etc/planeon/planeon.env, общем для всех четырёх юнитов ниже — те же переменные, что и planeon.env на странице установки через Docker Compose; здесь этот справочник не повторяется. Скопируйте тот файл в /etc/planeon/planeon.env и адаптируйте его для установки на хосте:

• DATABASE_URL и REDIS_ADDR должны указывать туда, где реально работают Postgres и Redis — здесь нет сети compose, которая резолвит имена сервисов вроде postgres или redis.
• GUACD_ADDRESS должен указывать туда, где вы разместите guacd (см. guacd ниже).

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

sudo chown planeon:planeon /etc/planeon/planeon.env
sudo chmod 640 /etc/planeon/planeon.env

systemd-юниты

Сохраните каждый из них как /etc/systemd/system/<имя-юнита>.

planeon-api.service

[Unit]
Description=Planeon API
After=network-online.target
Wants=network-online.target
# planeon-api должен видеть PostgreSQL и Redis, чтобы сообщить о
# готовности (см. «Проверьте установку» ниже). Запустите PostgreSQL и
# Redis -- как бы вы ими ни управляли на этом хосте или в сети -- прежде
# чем включать этот юнит.

[Service]
Type=simple
User=planeon
Group=planeon
EnvironmentFile=/etc/planeon/planeon.env
ExecStart=/opt/planeon/api/planeon-api
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

planeon-worker.service

[Unit]
Description=Planeon Worker
After=network-online.target
Wants=network-online.target
# То же примечание о порядке для PostgreSQL/Redis, что и у
# planeon-api.service.

[Service]
Type=simple
User=planeon
Group=planeon
EnvironmentFile=/etc/planeon/planeon.env
# api и worker используют общий сетевой стек этого хоста, в отличие от
# отдельных контейнеров в установке через Docker Compose, поэтому оба не
# смогут занять порт METRICS_ADDR по умолчанию 0.0.0.0:9090. Отдайте
# worker порт 9091, который платформа уже использует для него в другом
# месте -- см. «Наблюдаемость»: /docs/administration/observability
Environment=METRICS_ADDR=0.0.0.0:9091
ExecStart=/opt/planeon/worker/planeon-worker
Restart=on-failure
RestartSec=5
# Превышайте WORKER_SHUTDOWN_TIMEOUT из planeon.env (по умолчанию 30s),
# чтобы systemd не убивал сигналом SIGKILL задание, которое ещё корректно
# завершается -- аналогично stop_grace_period в установке через Docker
# Compose.
TimeoutStopSec=45

[Install]
WantedBy=multi-user.target

planeon-gateway.service

[Unit]
Description=Planeon Gateway
After=network-online.target planeon-guacd.service
Wants=network-online.target
Requires=planeon-guacd.service
# Также должен видеть PostgreSQL и Redis -- то же примечание о порядке,
# что и у planeon-api.service.

[Service]
Type=simple
User=planeon
Group=planeon
EnvironmentFile=/etc/planeon/planeon.env
ExecStart=/opt/planeon/gateway/planeon-gateway
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

planeon-web.service

[Unit]
Description=Planeon Web Console
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=planeon
Group=planeon
EnvironmentFile=/etc/planeon/planeon.env
ExecStart=/usr/bin/node /opt/planeon/web/server.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Точное имя файла точки входа и специфичные для Node.js переменные окружения (например, PORT/HOSTNAME) подтверждаются в примечаниях к релизу v1.0.0; server.js отражает стандартную структуру standalone-бандла Next.js, на котором построена веб-консоль.

guacd

В отличие от сервисов выше, guacd не распространяется как нативный бинарник — это собственная сборка guacd от Planeon с включённым декодированием H.264. В стандартном образе сообщества guacamole/guacd и в большинстве пакетов дистрибутивов этого декодирования нет, из-за чего сессии современных Windows (10/11, Server 2019+) отображаются чёрным экраном с одним лишь живым курсором. Запустите его как контейнер, тоже под управлением systemd, как и всё остальное (замените docker на podman везде, если используете этот рантайм):

[Unit]
Description=Planeon guacd
After=network-online.target docker.service
Wants=network-online.target
Requires=docker.service

[Service]
Type=simple
Restart=on-failure
RestartSec=5
ExecStartPre=-/usr/bin/docker rm -f planeon-guacd
ExecStart=/usr/bin/docker run --rm --name planeon-guacd -p 127.0.0.1:4822:4822 -e LOG_LEVEL=info planeon/guacd:v1.0.0
ExecStop=/usr/bin/docker stop -t 10 planeon-guacd

[Install]
WantedBy=multi-user.target

Сохраните это как /etc/systemd/system/planeon-guacd.service. Укажите в planeon.env для GUACD_ADDRESS значение 127.0.0.1:4822 (или другой адрес, если измените порт).

Примените миграции базы данных

Перед первым запуском planeon-api или planeon-worker — и перед каждым обновлением — примените миграции бинарником migrate. Это тот же инструмент, что и образ контейнера planeon/migrate, используемый в установке через Docker Compose, и из переменных planeon.env ему нужны только относящиеся к базе данных — DATABASE_URL (и DATABASE_MAX_CONNS, если вы его меняли) — именно их явно пробрасывает команда ниже; применение всех ожидающих миграций и завершение работы — его поведение по умолчанию, без дополнительных флагов:

set -a
source /etc/planeon/planeon.env
set +a
sudo -u planeon --preserve-env=DATABASE_URL,DATABASE_MAX_CONNS /opt/planeon/migrate/planeon-migrate

Миграции никогда не применяются автоматически при старте planeon-api или planeon-worker — тот же явный, отдельный шаг, что и в установке через Docker Compose, и по тем же причинам: видимые, проверяемые изменения схемы, а неудачная миграция останавливает выкладку до того, как новая версия начнёт обслуживать трафик.

Запустите платформу

sudo systemctl daemon-reload
sudo systemctl enable --now planeon-guacd.service
sudo systemctl enable --now planeon-api.service planeon-worker.service planeon-gateway.service planeon-web.service

Проверьте установку

systemctl status planeon-api planeon-worker planeon-gateway planeon-web planeon-guacd

Убедитесь, что каждый юнит в состоянии active (running). Затем проверьте готовность — каждый из planeon-api и planeon-worker отдаёт /readyz на своём ops-порту (METRICS_ADDR, 9090 у api и 9091 у worker с учётом переопределения выше):

curl -fsS http://127.0.0.1:9090/readyz   # planeon-api
curl -fsS http://127.0.0.1:9091/readyz   # planeon-worker

Оба возвращают 200, как только сходятся проверки PostgreSQL, Redis и состояния миграций; 503 называет первую неудавшуюся зависимость. api также отдаёт /healthz и /readyz на своём публичном порту (API_ADDR, по умолчанию 8080), если вам удобнее проверять через тот же адрес, что использует ваш обратный прокси. Точный формат ответа — в разделе Наблюдаемость → Семантика readiness. Если какой-то юнит не переходит в состояние active (running) или /readyz продолжает отказывать, см. Устранение неполадок.

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

Обновление

Тот же явный порядок, что и при установке, плюс перезапуск:

1. Скачайте новые артефакты и замените бинарники/бандл в /opt/planeon/... (сохраните /etc/planeon/planeon.env, добавив любые новые переменные, о которых сообщают примечания к релизу).

2. Повторно запустите бинарник migrate, как описано выше.

3. Перезапустите сервисы:

   sudo systemctl restart planeon-api planeon-worker planeon-gateway planeon-web

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