Что нужно

Исходный код открыт: склонируйте репозиторий командой git clone https://github.com/sleep3r/colloq.git. Нужны Docker с работающим daemon, Node.js 22 или новее и npm; зависимости ставятся из lockfile командой npm ci. Чтобы провести занятие на своём компьютере, исходники не нужны — достаточно pip install colloq. Production-процедура через k3s описана отдельно.

Файл .env для разработки создаёт первая же команда, которой он нужен: make dev, make up, make run, make host или make env-use. Это тот же файл, что пишет colloq start: ядра в Docker, свой случайный токен ядра, BIND_ADDR=127.0.0.1. .env.example — полный справочник настроек и шаблон серверной установки (в нём KERNEL_BACKEND=broker); копировать его в .env для разработки не нужно. make dev всегда слушает только 127.0.0.1. Для make up и make run адрес задаёт BIND_ADDR: без этой строки порт открыт на всех интерфейсах, включая Wi-Fi.

Занятие без исходников

pip install colloq
colloq start

Пакет для преподавателя содержит собранное приложение; нужны Node.js 22 или новее и Docker — у каждой комнаты свой контейнер с Python. colloq start поднимает занятие в этом терминале и открывает браузер, Ctrl+C сохраняет и останавливает его. Ссылку для аудитории выдаёт colloq host <имя>, проверку перед парой — colloq doctor, копию базы и файлов — colloq backup; остальное покажет colloq --help. Состояние хранится в ~/.colloq (другой каталог задаёт COLLOQ_HOME) и переживает переустановку пакета. Интерфейс пакета по умолчанию английский; язык меняется, как описано в руководстве.

Быстрый запуск в Docker

make up

Команда создаёт локальную конфигурацию, собирает образ ядра и запускает приложение. Каждая комната получает собственный контейнер; общего instance-wide Jupyter нет. Откройте приложение на http://localhost:3000 и завершите настройку владельца.

Данные и файлы находятся в локальных data/ и workspace/. Development backend имеет доступ к Docker socket; используйте его для доверенной локальной разработки, а не как production-границу безопасности.

Приложение на хосте

npm ci
make dev

make dev при необходимости собирает образ комнатного ядра, запускает сервер с перезагрузкой и Vite в этом терминале и открывает http://localhost:5173/admin; OPEN=0 — без браузера. Сервер слушает PORT из .env (по умолчанию 3000) только на 127.0.0.1. Перезагрузка сервера ядра комнат не трогает, Ctrl+C останавливает всё вместе с ядрами этой базы. На macOS отдельного разрешения не нужно: COLLOQ_UNSAFE_DEV_FILES больше ничего не меняет. Для сборки и фонового запуска host-сервера есть make run.

Если в .env старого клона осталась строка KERNEL_BACKEND=broker (раньше make up копировал .env.example), make dev откажет и назовёт исправление: замените её на KERNEL_BACKEND=docker или уберите .env в сторону, чтобы он был записан заново.

Development-окружения

make env-list
make env-new NAME=nlp
# Измените требования в kernel/environments/
make env-build NAME=nlp
make env-use NAME=nlp

Это команды Docker-разработки. В production окружения публикуются заранее и выбираются из digest-каталога, как описано в руководстве окружений.

Тексты интерфейса

Парные переводы находятся в shared/locales/: admin.ts, room.ts, server.ts, activity.ts и common.ts. Добавляйте русский и английский варианты под одним ключом, а в месте показа вызывайте tr(key, params) из shared/i18n.ts. Подставляйте имена и другие переменные параметрами; для счётчиков используйте формы множественного числа, для дат и чисел — общие функции форматирования.

В Svelte перевод должен вычисляться реактивно при показе: перевод, сохранённый в константу при загрузке модуля, не обновится. Для нативных элементов редактора есть подписка на смену языка; пересоздавать весь редактор ради подписи не нужно. Служебные значения протокола, имена файлов и пользовательские тексты через переводчик не пропускаются. Проверка tests/i18n.test.mts сверяет наличие обоих языков и совпадение параметров; поведение переключателя проверяют тесты instance-language, admin-language и language-room.

Проверки изменений

npm run typecheck
npm test
npm run build

Запускайте также относящиеся к изменению интеграционные сценарии из tests/README.md. Локальный green test не заменяет deployment smoke, сетевые проверки, backup/restore и реальную GPU-операцию на целевой VM.

Эта документация собирается из docs/pages/ru и docs/pages/en командой python3 docs/build.py; сгенерированный HTML руками не правят. Коммитьте пересобранный site/docs вместе с источниками: проверка CI «Docs up to date» пересобирает его и падает при расхождении. Удаляя страницу, удалите (git rm) и её site/docs/<slug>.html.

Если ядро не запускается, проверьте Docker daemon, наличие образа, права на socket и пути workspace. Не подставляйте один общий Jupyter endpoint как временную замену отдельным комнатам.