Установка через мастер

Мастер подготовки (provisioning wizard) — рекомендуемый способ установки self-hosted Copula. Он находится в приложении Copula и запускается до появления любого Space — мастер готовит чистый сервер от начала до конца и возвращает готовый URL Space.

Предварительные условия: сервер, соответствующий требованиям, и лицензионный токен.

Шаги мастера

1. SSH — укажите хост, SSH-порт (по умолчанию 22), SSH-пользователя и метод аутентификации (пароль или приватный ключ).
2. License — вставьте LICENSE_TOKEN, скопированный из кабинета.
3. Env — настройте окружение бэкенда:
   • сначала учётные данные администратора: ADMIN_USER и ADMIN_PASS;
   • затем блок провайдера моделей;
   • затем секреты: JWT_SECRET (ровно 128 hex-символов) и ENCRYPTION_KEY (32 символа) — мастер может предзаполнить и перегенерировать оба;
   • расширенные поля опциональны.
4. Domain — выберите автоматически сгенерированный поддомен inst-<slug>.copul4.com или укажите собственный FQDN (его запись A уже должна указывать на сервер).
5. Pre-flight — мастер выполняет SSH-проверки целевого хоста.
6. Progress — запускается деплой.

Что делает деплой

Пайплайн деплоя выполняет шаги в следующем порядке:

install_docker → dns_setup → render_compose → upload_files → pull_images
→ start_postgres → run_migrations → start_backend → start_proxy → await_health

Шаг start_postgres пропускается, если настроена внешняя база данных.

Если вы используете внешний PostgreSQL (database_mode=external / собственную базу данных), на сервере должно быть доступно расширение pgvector (семейство образов pgvector/pgvector или установленное расширение): миграция 0059 выполняет CREATE EXTENSION vector и завершится ошибкой без него.

Что появляется на хосте

Стек разворачивается в /root/copula:

• /root/copula/docker-compose.yml
• /root/copula/.env (права файла 0600)
• /root/copula/Caddyfile

Сервисы:

Сервис	Образ / роль
copula-postgres	pgvector/pgvector:0.8.6-pg16 — только в режиме с подготовленной БД; данные в /root/copula/data; наружу хоста не публикуется
copula-migrate	Одноразовая init-задача, собранная из образа самого copula-api (migrate CLI в /usr/local/bin/migrate, файлы миграций в /migrations); запускается перед бэкендом через depends_on: service_completed_successfully
copula-back	Опубликованный образ бэкенда; порт хоста 8901 → ${BACKEND_PORT}; тома /root/copula/workspace → /workspace, /root/copula/ssh → /root/.ssh, ./.env → /config/.env:ro, /var/run/docker.sock
copula-cocoindex	cocoindex/cocoindex-code:full — демон поиска по коду
copula-caddy	caddy:2.11.4-alpine — публикует порты 80/443, автоматически получает сертификат Let's Encrypt для домена инстанса, проксирует запросы на copula-back

После деплоя

Мастер завершается URL space вида https://<domain>. Добавьте этот URL как Space в приложении Copula, чтобы начать работу.

Конфигурация моделей по умолчанию для новых установок — MODEL_PROVIDER=copula с MODEL_NAME=copula-base: LLM-роутер кабинета, которому не нужен API-ключ (учётные данные — лицензионный токен). Провайдеры openrouter и custom выбираются на шаге Env; см. справочник переменных окружения.

Следующий шаг

Reverse proxy и TLS →