Linux¶

Portable-бандл для Linux поставляется как tar.gz для x64. Он содержит Node.js 22, приложение, rg и bin/synth; системные пакеты Node.js не нужны. Установка возможна в пользовательский контур (systemd user) или как сервис (systemd system).

Поддерживаемые системы¶

Семейство	Версии	Пакетный менеджер
RHEL	8, 9	`dnf`
Ubuntu	20.04, 22.04, 24.04	`apt`
Debian	11, 12	`apt`
Astra Linux	1.8.x	`apt`
RED OS	8	`dnf`

Архитектура — x64. Требуется glibc >= 2.28. Проверьте перед установкой:

uname -m
getconf GNU_LIBC_VERSION
cat /etc/os-release

uname -m должен вернуть x86_64, getconf — glibc 2.28 или новее. На системах с musl (Alpine) portable-бандл не запускается — используйте контейнерную поставку.

Распаковка и проверка¶

cd <bundle-dir>
sha256sum -c SHA256SUMS
tar -xzf synth-<version>-linux-x64.tar.gz
cd synth-<version>-linux-x64

В каталоге должны быть bin/synth, manifest.json, SHA256SUMS, LICENSES и каталоги runtime/приложения. Проверьте запуск:

./bin/synth --version

Установка¶

Вариант 1. Установщик из бандла¶

В бандл входит скрипт установки (имя и флаги уточняются в manifest.json). Запускайте его от того пользователя, в чьём контуре ставите Synth:

# системная установка (нужен root)
sudo ./install.sh

# пользовательская установка (без root)
./install.sh

Установщик раскладывает файлы и настраивает запуск (unit-файл или ярлык); точный набор шагов и флаги — в manifest.json/README бандла. Дальше проверьте systemctl-раздел ниже и задайте API-ключ.

Вариант 2. Ручная раскладка¶

Если установщик недоступен или нужна нестандартная раскладка, разложите файлы вручную. Пример для системной установки в /opt/synth (финальный путь может отличаться — сверьтесь с manifest.json):

sudo install -d -m 0755 /opt/synth
sudo cp -a . /opt/synth/
sudo ln -s /opt/synth/bin/synth /usr/local/bin/synth

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

sudo useradd --system --home-dir /var/lib/synth --shell /usr/sbin/nologin synth
sudo install -d -m 0750 -o synth -g synth /var/lib/synth/data

Для пользовательской установки:

install -d -m 0755 ~/.local/opt
cp -a . ~/.local/opt/synth
ln -s ~/.local/opt/synth/bin/synth ~/.local/bin/synth

API-ключ¶

В системной установке ключ удобно хранить в env-файле с правами 0600:

sudo install -d -m 0700 /etc/synth
printf 'SYNTH_API_KEY=%s\n' '<api-key>' | sudo tee /etc/synth/synth.env >/dev/null
sudo chmod 600 /etc/synth/synth.env

SYNTH_API_KEY даёт роль ADMIN. Это режим без Keycloak; для командной работы с ролями используйте OIDC — Keycloak и API-key.

Ключ — это полный доступ

Не передавайте ключ в командной строке, если её видно другим пользователям (ps), и не храните его в репозитории. Для systemd используйте EnvironmentFile, для контейнера — Secret или env-файл.

systemd: системный сервис¶

Пример unit-файла /etc/systemd/system/synth.service. Итоговый unit входит в бандл и может отличаться путями; этот пример проверяем при ручной раскладке.

[Unit]
Description=Synth
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=synth
Group=synth
WorkingDirectory=/opt/synth
EnvironmentFile=/etc/synth/synth.env
ExecStart=/opt/synth/bin/synth serve --host 0.0.0.0 --port 4300 --data-dir /var/lib/synth/data
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now synth
sudo systemctl status synth
sudo journalctl -u synth -f

Проверка:

curl -fsS http://127.0.0.1:4300/health

systemd: пользовательский сервис¶

Для локальной машины удобнее user-unit: он не требует root и работает в контексте пользователя. Файл — ~/.config/systemd/user/synth.service:

[Unit]
Description=Synth (user)

[Service]
Type=simple
WorkingDirectory=%h/.local/opt/synth
EnvironmentFile=%h/.config/synth/synth.env
ExecStart=%h/.local/opt/synth/bin/synth serve --home %h/.synth
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

mkdir -p ~/.config/synth
chmod 700 ~/.config/synth
printf 'SYNTH_API_KEY=%s\n' '<api-key>' > ~/.config/synth/synth.env
chmod 600 ~/.config/synth/synth.env

systemctl --user daemon-reload
systemctl --user enable --now synth
systemctl --user status synth
journalctl --user -u synth -f

По умолчанию synth serve слушает 127.0.0.1:4300. Чтобы сервис запускался без входа пользователя в систему:

sudo loginctl enable-linger "$USER"

SELinux (RHEL, RED OS, Astra)¶

Не отключайте SELinux глобально. Если сервис не стартует или не может прочитать файлы, посмотрите отказы:

getenforce
sudo ausearch -m avc -ts recent

Типовой случай — неверный контекст у каталога установки. Для /opt/synth:

sudo semanage fcontext -a -t bin_t '/opt/synth/bin(/.*)?'
sudo restorecon -Rv /opt/synth/bin

Если semanage не установлен, поставьте policycoreutils-python-utils (RHEL/RED OS) или policycoreutils (Debian/Astra) из локального зеркала. Порт 4300 обычно не требует отдельного правила SELinux; если AVC указывает на name_bind, разрешите порт через semanage port или выберите порт из разрешённого диапазона. Не выполняйте setenforce 0 как «решение».

Брандмауэр¶

Серверный инстанс должен быть доступен только из доверенной сети. Откройте порт 4300/tcp (или тот, который задан в unit-файле).

RHEL / RED OS:

sudo firewall-cmd --permanent --add-port=4300/tcp
sudo firewall-cmd --reload

Ubuntu / Debian / Astra:

sudo ufw allow 4300/tcp
sudo ufw status

Если перед Synth стоит reverse proxy с TLS, наружу публикуйте только его, а 4300 оставьте на loopback или во внутренней сети.

Особенности дистрибутивов¶

Дистрибутив	Что учесть
RHEL 8/9	SELinux включён по умолчанию; проверьте контекст `/opt/synth` и откройте порт в `firewall-cmd`
RED OS 8	RHEL-совместимый стек; те же шаги SELinux и `firewall-cmd`
Ubuntu 20.04/22.04/24.04	`ufw` часто включён; glibc в поддерживаемых версиях >= 2.28
Debian 11/12	`ufw` может быть выключен; проверьте `getconf GNU_LIBC_VERSION`
Astra Linux 1.8.x	`apt`; SELinux может быть включён — действуйте через `ausearch`/`semanage`, не отключайте мандатный контроль

Обновление и удаление¶

Обновление — не synth update, а замена бандла: остановить сервис, распаковать новую версию, выполнить synth migrate --yes, запустить и проверить. Полный порядок — Эксплуатация.
Удаление — sudo ./uninstall.sh из бандла или synth uninstall; по умолчанию данные сохраняются. Для удаления данных — --purge --yes (необратимо).