Работа с проектом

1. Docker Compose

Для основного сценария нужен Docker Desktop или Docker Engine с Compose. Установленный на компьютере GNU Octave не требуется: решатель GNU Octave 11.3.0 работает внутри контейнера.

Из корня репозитория выполните:

docker compose up --build

Для старой отдельной команды Compose эквивалентный запуск выглядит так:

docker-compose up --build

После готовности контейнеров откройте http://127.0.0.1:8080. Создайте модель или загрузите TXT-файл, затем нажмите Run analysis. Интерфейс покажет состояние и журнал расчёта, а готовый результат автоматически откроется в постпроцессоре.

Остановить приложение можно сочетанием Ctrl+C в его терминале. Удалить созданные контейнеры и сеть:

docker compose down

2. Настройка и ограничения

Снаружи публикуется только Nginx на loopback-интерфейсе. FastAPI и Octave доступны лишь во внутренней сети Compose. API принимает модель, но не произвольные скрипты, пути или выражения Octave. Один worker выполняет расчёты последовательно; остальные принятые задания ожидают в очереди.

Например, в PowerShell приложение на порту 8090 можно запустить так:

$env:MKEF_PORT = "8090"
docker compose up --build

3. Проверка проекта

Контейнерный smoke-тест

При работающем стеке запустите из корня репозитория:

./scripts/compose_smoke_test.ps1

Интеграционные тесты Python и Octave

docker build --target test -t mkef-solver-test -f docker/solver.Dockerfile .
docker run --rm mkef-solver-test

Тесты браузерных приложений

Откройте с диска файлы preprocessor/tests/index.html, postprocessor/tests/index.html и shared/tests/index.html. Успешный результат содержит только строки PASS и итоговое число пройденных проверок.

Если браузер запрещает локальные сценарии, запустите из корня репозитория:

python -m http.server 8000

Затем откройте тесты препроцессора, тесты постпроцессора и общие тесты. Сервер останавливается сочетанием Ctrl+C.

Локальные тесты численного ядра и требования к GNU Octave описаны в главе 12.

4. Автономные веб-интерфейсы

preprocessor/index.html и postprocessor/index.html можно открыть прямо с диска. В таком режиме доступны создание и редактирование TXT-моделей, а также просмотр ранее сохранённых JSON-результатов. Запуск расчёта из препроцессора доступен только через контейнерный API.

Препроцессор

Узлы и элементы создаются на SVG-поле, а точные координаты, свойства, опоры и нагрузки редактируются в таблицах. TXT-файл можно открыть кнопкой Open TXT или перетащить в окно. Координатная сетка, её размер и шаг привязки настраиваются в панели Canvas settings; координаты выбранного узла доступны также в панели Selection.

Выбранный вид расчёта сохраняется в секции analysis. Её синтаксис и правила совместимости старых файлов приведены в описании формата.

Постпроцессор и единицы

Постпроцессор не преобразует численные значения. Обозначения берутся из metadata.units экспортированного JSON и должны соответствовать согласованной системе исходной модели. Амплитуда нормированной собственной формы произвольна и не является физическим перемещением.

5. Структура репозитория

6. Где искать остальные сведения

• формат входного файла, единицы, элементы, опоры и нагрузки;
• статический расчёт и статический вид постпроцессора;
• модальный расчёт и анимация форм;
• переходный расчёт, временные истории и спектр;
• локальные усилия, деформации и напряжения элементов;
• архитектура, разреженная сборка и карта проверок;
• полный численный пример Mario Paz;
• работа без Docker непосредственно в GNU Octave.

Проверки равномерных нагрузок

Полный набор run_octave_tests включает test_element_loads. Контейнерные тесты API проверяют CaseUniformFrame через настоящий GNU Octave. Браузерные наборы доступны по preprocessor/tests/, postprocessor/tests/ и shared/tests/.

Для автоматического прогона интерфейса установите Playwright в среде разработки, экспортируйте CaseUniformFrame в output/uniform-result.json и запустите node scripts/test_browser.cjs. При необходимости переменная MKEF_PLAYWRIGHT_MODULE задаёт путь к установленному модулю Playwright. Скрипт проверяет каскадное удаление, Undo/Redo, чтение JSON v2 и сохраняет снимки в output.

Публичный VPS и локальная работа

Лабораторные выполняются только в установленном GNU Octave без Docker: setup; addpath(fullfile(pwd, 'reference', 'examples')); results = run_reference_examples();. Локальное веб-приложение в Docker — отдельный сценарий; прежние параметры и команды сохраняются.

Публичный режим использует те же образы с дополнительным compose.public.yaml. Собирайте исходники локально; публикация образов из MKE-F-PUBLIC не предусмотрена. Сначала подготовьте .env и сети по public-deployment.md:

# First prepare private .env and shared networks: see public-deployment.md
docker compose -f compose.yaml -f compose.public.yaml -f compose.caddy.yaml config --quiet
docker compose -f compose.yaml -f compose.public.yaml -f compose.caddy.yaml up --build -d

Не используйте compose.release.yaml и образы основного MKE-F для этого сайта. Собирайте web и solver из одного проверенного коммита MKE-F-PUBLIC. Версии исходников публикуются в закрытом GitHub-репозитории; выберите тег релиза (начальный — v0.8.3) и зафиксируйте SHA. Номер версии хранится в VERSION, заметки — в RELEASES.md, порядок выпуска — в DEVGUIDE.md. Публичные настройки MKEF_PUBLIC_* и HTTP-бюджеты MKEF_HTTP_* перечислены в публичном Compose-файле.

Начальный профиль: два обработчика, 8 активных заданий, ожидание до 180 секунд и расчёт до 60 секунд; 200 узлов, 400 элементов, 800 степеней свободы (300 для модального анализа), 5000 шагов и 100000 сочетаний «СС × отсчёт». Дополнительно ограничены записи опор, нагрузок, освобождений и MPC. Текущие ограничения доступны через /api/v1/capabilities; режим должен быть public.

На Ubuntu используйте общий Caddy из BGModeller, отдельные секреты приложений и приватные сети по инструкции public-deployment.md. Caddy автоматически получает и продлевает HTTPS-сертификаты. Web и solver не публикуют порты; внутренний Nginx обслуживает статику и буферизует загрузки. API проверяет доверенный прокси и ограничивает частоту до чтения тела. CDN не предполагается. Один процесс API владеет очередью и HTTP-счётчиками.

Каталог /jobs — временное хранилище в памяти, не папка output проекта. В публичном режиме вход, результат и сведения о задании доступны 5 минут после завершения; локальный срок остаётся 24 часа. После истечения срока API возвращает 404, файлы удаляются ближайшей очисткой с сохранением начатого скачивания. При остановке контейнера данные исчезают раньше. Ссылка открывает результат любому, кто её знает; отмена требует секрета создавшего задание браузера, регистрация не нужна.

Сохраняйте TXT модели и JSON результата. Открытая страница сохраняет загруженный результат и позволяет скачать JSON даже после удаления серверной копии. Сохранённый JSON открывается без повторного расчёта; TXT позволяет повторить расчёт.

Перед публикацией нужны нагрузочные испытания на целевом VPS (ориентир 4 vCPU / 8 ГБ), проверка HTTPS и закрытых портов извне. Контейнер имеет общий предел памяти 6 ГБ для API, двух Octave и временных файлов. Аварийно завершившийся контейнер перезапускается, но состояние unhealthy само по себе перезапуска не вызывает. Полный перечень проверок находится в public-deployment.md.