Установка и запуск из готового бинарника#

Для тех, у кого уже есть — или кто хочет получить — просто бинарник opendray, без мастера установки, который трогает вашу машину. Этот путь подходит для:

• npm install -g opendray / npx opendray — npm-пакет поставляется с официальным Go release-бинарником (см. README → npm / npx).
• Загрузки со страницы релизов — скачайте opendray_*_<os>_<arch>.tar.gz со страницы релизов.
• Скриптовые / эфемерные окружения — CI runner-ы, golden image-ы, управление конфигурацией (Ansible, Nix, Docker), или любой хост, где у вас уже работает собственный Postgres и супервизор процессов.

Бинарник — это весь шлюз целиком: React-админка встроена в него, поэтому Node-рантайм, отдельный сервер статики и сборка не нужны. Чего он не делает — так это ничего за вас не настраивает. Таков компромисс: вы приносите базу данных PostgreSQL и способ держать процесс запущенным, а взамен ничего не устанавливается, не конфигурируется и не регистрируется за вашей спиной.

Хотите, чтобы всё сделали за вас? На свежей Linux / macOS-машине однострочный установщик поднимает Postgres, устанавливает AI-CLI, прописывает конфиг и регистрирует сервис примерно за 5–10 минут. См. README → Однострочный установщик или подробный гайд getting-started.md.

Этот гайд проведёт вас от «бинарник есть в PATH» до «шлюз работает» за пять шагов, а затем покажет, как запустить его как сервис.

Шаг 1 — Получите бинарник#

Через npm (любая ОС с Node ≥ 18)#

Нужный платформенный бинарник (opendray-{linux,darwin}-{x64,arm64}) выбирается автоматически через optionalDependencies — никакого postinstall-хука и никаких сетевых вызовов на момент установки. Не передавайте --no-optional: это пропустит платформенный пакет и оставит launcher без бинарника для запуска.

Через архив со страницы релизов#

Проверка#

Поддерживаемые платформы: Linux (x64, arm64) и macOS (x64, arm64). Нативный Windows не упакован — используйте WSL2 и следуйте пути для Linux.

Шаг 2 — Обеспечьте PostgreSQL 15+ с pgvector#

opendray хранит всё (сессии, память, аудит-лог) в PostgreSQL, и его подсистема памяти требует расширения pgvector. Поддерживаемые версии сервера: 15, 16, 17.

Если у вас уже работает Postgres, создайте базу данных и роль только для CRUD, затем однократно включите расширение от суперпользователя:

После того как расширение установлено, роль с правами только на CRUD выполняет миграции без каких-либо дополнительных прав суперпользователя. Никогда не указывайте в opendray роль суперпользователя для рантайма — дайте ему проектную учётку и меняйте пароль независимо.

Шаг 3 — Настройте конфигурацию#

opendray читает конфиг из TOML-файла или только из переменных окружения (12-factor) — env всегда имеет приоритет над файлом. Единственное жёсткое требование — URL базы данных; всё остальное имеет значение по умолчанию.

Вариант A — переменные окружения (хорошо для контейнеров / эфемерных хостов)#

Запустите opendray serve без флага -config, и он полностью загрузится из переменных окружения.

Вариант B — config.toml#

Минимум для редактирования:

См. config.example.toml — полностью аннотированный файл (логирование, обнаружение простоя сессий, бэкапы, vault, MCP). Передайте его с -config config.toml командам ниже. Держите секреты вне TOML на общих хостах — задайте OPENDRAY_DATABASE_URL / OPENDRAY_ADMIN_PASSWORD через env и оставьте файл без секретов.

Шаг 4 — Примените схему#

Идемпотентно — повторный запуск не даёт эффекта, если схема актуальна. Это должно завершиться успешно до первого запуска serve.

Шаг 5 — Запустите#

Это запускается на переднем плане (Ctrl-C останавливает). Теперь у вас есть:

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

Запуск как сервис#

opendray serve — именно та команда, которую должен вызывать start-команда юнита сервиса. opendray поставляется с захардёненными, готовыми к использованию юнитами; шаги ниже аналогичны README → Развёртывание в продакшене, который является авторитетным справочником (полный bootstrap, заметки по sandboxing, reverse-proxy/TLS).

Linux — systemd#

Репозиторий поставляется с захардёненным юнитом в deploy/systemd/opendray.service (запускает migrate как ExecStartPre, секреты через EnvironmentFile, рестарт on-failure, sandboxing syscall/filesystem).

Нет systemd? (LXC без него, OpenRC, runit, s6, supervisord…) Направьте ваш супервизор на opendray serve -config /etc/opendray/config.toml и запустите opendray migrate один раз как шаг pre-start. См. README → Развёртывание в продакшене §B.

macOS — launchd#

Репозиторий поставляется с LaunchDaemon в deploy/launchd/com.opendray.opendray.plist (запускается при загрузке, рестартует при краше, логи в /usr/local/var/log/opendray/).

Рестарт: sudo launchctl kickstart -k system/com.opendray.opendray. Выгрузка: sudo launchctl bootout system/com.opendray.opendray.

Оба юнита полностью задокументированы — включая раскладку секретов и почему MemoryDenyWriteExecute оставлен выключенным — в deploy/README.md.

Обновление#

Способ обновления зависит от того, как вы установили:

• Установлено через npm — обновляйте через ваш пакетный менеджер. opendray update заменил бы бинарник внутри node_modules за спиной npm и был бы затёрт при следующей установке, поэтому здесь его не используйте.

  [object Promise]

• Загрузка со страницы релизов / установка через мастер — бинарник самообновляется на месте (скачивает последний релиз, верифицирует SHA-256, атомарно заменяет себя):

  [object Promise]

Устранение неполадок#

the matching platform package "opendray-…" was not installed npm был запущен с --no-optional, или установка была прервана. Повторно запустите npm install -g opendray (без --no-optional).

unsupported platform npm-пакет покрывает только Linux/macOS на x64/arm64. На других платформах — соберите из исходников: см. quickstart.md.

config: database.url is empty Не задан ни OPENDRAY_DATABASE_URL, ни [database].url. Задайте одно из двух (Шаг 3).

connection refused при migrate/serve Postgres не запущен или DSN неверный. Убедитесь, что сервер работает и хост/порт/учётные данные в вашем DSN верны.

pgvector / extension "vector" is not available Расширение не установлено на сервере или не включено в базе opendray. Повторите Шаг 2 (установите OS-пакет, затем выполните CREATE EXTENSION vector от суперпользователя).

Port already in use Измените OPENDRAY_LISTEN (или listen в config.toml) на свободный порт.

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

• README → Развёртывание в продакшене — полный справочник по деплою (systemd / launchd / собственный супервизор, hardening, reverse-proxy)
• docs/operator-guide.md — эксплуатация: топология reverse-proxy/TLS, шифрованные бэкапы БД, экспорт/импорт данных
• docs/integration-guide.md — написание внешней интеграции через REST + WebSocket API
• docs/getting-started.md — управляемый сквозной гайд, если вы предпочитаете не собирать всё по кускам самостоятельно