Docker / Docker Compose¶
Synth поставляется готовым образом git.itphx.ru/itphx/synth и файлом
docker-compose.yml. Это самый простой способ развернуть платформу, если не
хочется устанавливать Node.js: образ уже содержит и core, и веб-интерфейс.
Быстрый запуск образа¶
docker run -p 4300:4300 \
-e SYNTH_API_KEY=my-secret-key \
-v synth-data:/var/synth/data \
git.itphx.ru/itphx/synth:0.13.10
Откройте http://localhost:4300 и введите ключ
my-secret-key. Образ сам слушает 0.0.0.0:4300 и хранит данные в томе
/var/synth/data.
Docker Compose¶
Готовый docker-compose.yml лежит в корне репозитория. По умолчанию он
поднимает один сервис synth; остальные сценарии включаются профилями:
ollama (локальные модели), postgres (хранилище в базе), all-in-one
(сервер с инструментами и отдельный UI) и split (тонкий сервер плюс
исполнители).
Откройте http://localhost:4300 и введите ключ
my-secret-key. Логи сервиса: docker compose logs -f synth.
Состав Compose¶
| Сервис | Профиль | Порт | Назначение |
|---|---|---|---|
synth |
по умолчанию | 4300 |
Платформа целиком: сервер + UI, файловое хранилище, том synth-data |
synth-backend |
all-in-one |
5000 |
Сервер с инструментами; команды исполняются в его процессе (inline) |
synth-ui |
all-in-one, split |
5002 |
Веб-интерфейс; проксирует API на synth-backend |
synth-backend-split |
split |
5000 |
Тонкий сервер без инструментов; команды уходят исполнителю |
synth-executor |
split |
5100 (внутри сети) |
Исполнитель команд, общий том synth-workspace |
postgres |
postgres |
5432 |
База для storage.backend: postgres, том postgres-data |
ollama |
ollama |
11434 |
Локальный сервер моделей, том ollama-data |
Простой docker compose up -d поднимает только synth. Сервисы с профилем
запускаются явно, например docker compose --profile all-in-one up -d или
docker compose --profile split up -d; профиль postgres можно сочетать с
любым из них.
Compose уже настроен на работу с Ollama внутри сети Docker: провайдер указывает
на нативный http://ollama:11434 (без /v1) — так применяются num_ctx,
think и инструменты.
Хранилище: файлы и PostgreSQL¶
По умолчанию состояние лежит в томе synth-data (файловое хранилище). Для
командной работы его можно перевести в PostgreSQL:
cat >> .env <<'EOF'
SYNTH_STORAGE_BACKEND=postgres
SYNTH_POSTGRES_PASSWORD=change-me
EOF
docker compose --profile postgres up -d
В Compose хост базы — postgres, база и пользователь — synth. Параметры
соединения задаются переменными SYNTH_POSTGRES_HOST, SYNTH_POSTGRES_PORT,
SYNTH_POSTGRES_DATABASE, SYNTH_POSTGRES_USER. Пароль хранится только в
SYNTH_POSTGRES_PASSWORD или в файле
{каталог данных}/secrets/postgres-password.
Резервная копия — база и том
При postgres в томе остаются секреты, служебные метаданные и двоичные
объекты: вложения, артефакты, содержимое скиллов, логи процессов. Поэтому
архива каталога данных недостаточно — сохраняйте и базу, и том
synth-data.
Подробнее о параметрах, деградации и переносе данных — Конфигурация.
Раздельное исполнение (split)¶
В split-топологии сервер не запускает команды сам: shell, git и поиск выполняются в отдельном контейнере-исполнителе. Управляющий слой остаётся тонким, а инструменты и их зависимости живут в исполнителе.
Подготовьте токен доверия — сервер читает его из файла, исполнитель из переменной окружения:
TOKEN=$(openssl rand -base64 32)
printf '%s' "$TOKEN" > .executor-token
printf 'SYNTH_EXECUTOR_TOKEN=%s\n' "$TOKEN" >> .env
docker compose --profile split up -d
Что поднимается:
synth-backend-split— сервер без инструментов, сSYNTH_EXECUTION_MODE=remote;synth-executor— исполнитель на внутреннем порту5100;synth-ui— веб-интерфейс;- общий том
synth-workspace— один и тот же путь в сервере и исполнителе.
Адрес исполнителя уже задан в Compose (http://synth-executor:5100). Токен
сервер читает только из файла /etc/synth/executor/token, в который
монтируется .executor-token. Если файла нет, Docker создаст на его месте
каталог, и сервер не стартует.
Хранилище и общий том
Если управляющий слой работает в нескольких репликах, состояние должно лежать в PostgreSQL: файловые данные не разделяются между контейнерами. Рабочий том при нескольких исполнителях обязан поддерживать одновременную запись — в Kubernetes это класс ReadWriteMany.
Варианты образов (flavor)¶
Для сервера и исполнителя есть несколько вариантов образа — от slim до full. Набор инструментов в образе определяет, какие команды доступны агенту.
| Flavor | Что внутри | Когда выбирать |
|---|---|---|
slim |
только управляющий слой, без инструментов | сервер в split-топологии |
core |
базовый набор: shell, git, поиск | обычная работа, all-in-one |
dev |
сборка, компиляторы, клиенты БД | разработка |
devops |
инфраструктурные утилиты и диагностика | эксплуатация |
browser |
Chromium и Playwright | браузерная автоматизация |
full |
всё перечисленное | универсальный исполнитель |
Тонкий сервер публикуется как synth-backend:<версия> — без суффикса; для
остальных вариантов тег выглядит как <версия>-<flavor>, например
0.13.10-core. Тег latest не публикуется.
Docker-сокет не монтируется
Ни один образ не получает доступ к docker.sock и не управляет соседними
контейнерами на хосте. Для задач, которым нужен Docker, используйте
внешний runner или отдельный исполнитель с нужными правами.
Переменные окружения¶
| Переменная | Обязательна | Назначение |
|---|---|---|
SYNTH_API_KEY |
да | Ключ доступа к UI и API |
SYNTH_STORAGE_BACKEND |
нет | file (по умолчанию), memory или postgres |
SYNTH_POSTGRES_PASSWORD |
для PostgreSQL | Пароль базы; альтернатива — файл в каталоге секретов |
SYNTH_EXECUTION_MODE |
нет | inline (по умолчанию) или remote для split |
SYNTH_EXECUTOR_TOKEN |
для split | Токен доверия исполнителя; то же значение — в файле у сервера |
SYNTH_PROVIDER_OLLAMA_URL |
для Ollama | Нативный адрес Ollama (http://ollama:11434, без /v1) |
SYNTH_PROVIDER_OLLAMA_MODEL |
для Ollama | Модель, например qwen3.8:27b |
SYNTH_PROVIDER_OLLAMA_TYPE |
для Ollama | Тип провайдера — ollama |
SYNTH_PROVIDER_<NAME>_API_KEY |
для внешних API | Ключ провайдера |
Провайдеры можно задать и через CLI/UI уже после запуска — подробности в Провайдеры и модели.
Ollama в Compose¶
Локальные модели одной командой
Запустите профиль и загрузите модель:
После этого Ollama доступна приложению по адресу http://ollama:11434
(нативный /api/chat), а наружу — на http://localhost:11434.
Контекстное окно (num_ctx) можно задать через Synth — флагом --num-ctx
у synth config provider add, переменной SYNTH_PROVIDER_OLLAMA_NUM_CTX
или полем num_ctx/numCtx в POST/PATCH /api/v2/providers (приоритет
выше contextWindow модели). num_ctx передаётся в теле запроса к
нативному /api/chat и применяется. Если базовый URL задан со старым
суффиксом /v1, Synth снимет его и уйдёт на /api/chat, предупредив в лог;
для OpenAI-совместимого пути нужен провайдер type: openai/generic.
Дополнительно у сервиса ollama в docker-compose.yml выставлена переменная
OLLAMA_CONTEXT_LENGTH (по умолчанию 262144 — серверный дефолт окна, окно
256k токенов).
Данные и тома¶
Данные Synth живут в именованном томе synth-data (внутри —
/var/synth/data): сессии, проекты, провайдеры, модели, агенты, секреты.
При storage.backend: postgres состояние переезжает в том postgres-data, а
в synth-data остаются секреты, служебные метаданные и двоичные объекты.
Модели Ollama — в томе ollama-data, общий рабочий каталог split-топологии —
в томе synth-workspace.
docker compose downостанавливает сервисы, но сохраняет тома.docker compose down -vудаляет тома вместе с данными — используйте осознанно.- Список томов:
docker volume ls.
Обновление версии¶
# для образа, запущенного вручную
docker pull git.itphx.ru/itphx/synth:0.13.10
docker rm -f synth
# затем запустите контейнер заново
Обновление не затрагивает тома, поэтому история и настройки сохраняются.
Фиксируйте версию
Тег latest не публикуется — в реестре остаются только версионные теги.
Поэтому docker pull git.itphx.ru/itphx/synth без тега не сработает:
указывайте конкретную версию, например :0.13.10.
Один контейнер — вся платформа
Базовый образ synth содержит и серверный движок, и собранный SPA. Отдельные
контейнеры для UI или исполнителя нужны только в выбранной топологии
all-in-one или split.
Что дальше¶
- Конфигурация — хранилище, исполнение и лимиты.
- Kubernetes / Helm — командное развёртывание в кластере.
- Локальный запуск — без Docker, на Node.js.
- Провайдеры и модели — подключить внешние API.
- Гибридный режим — локальные файлы + корпоративный сервер.