seaf/seaf-archtool-core repository overview

⁠Запуск SEAF ArchPortal на рабочей машине архитектора

К основной документации⁠

Самый простой способ запустить портал. Используется готовый Docker-образ с DockerHub, манифесты загружаются с локального диска. Аутентификация, GitLab и PlantUML не нужны - рендеринг диаграмм выполняется на публичном сервере.

Этот вариант подходит для знакомства с инструментом, разработки и отладки метамоделей на своей машине.

⁠Что будет запущено

PlantUML-диаграммы рендерятся на публичном сервере https://seaf.su/seafplantuml, дополнительные контейнеры не требуются.

⁠Пререквизиты

• Docker установлен и запущен
• Свободно не менее 2 GB оперативной памяти
• Каталог с YAML-манифестами на локальной машине (или готовность создать тестовые)

⁠Шаг 1. Подготовка манифестов

Создайте каталог, в котором будут храниться ваши архитектурные манифесты. Для начала достаточно нескольких тестовых файлов.

mkdir -p ~/seaf-workspace
cd ~/seaf-workspace

Создайте файл root.yaml - точку входа для портала:

imports:
  - documents.yaml

Создайте файл documents.yaml с тестовым документом:

docs:
  superdoc.congrats:
    icon: lightbulb_outline
    location: DocHub/Тестовый документ
    description: Тестовый документ
    type: markdown
    source: manual.md

Создайте файл manual.md:

# Тестовый документ
Поздравляем, вы запустили SEAF ArchPortal.

Все три файла должны лежать в каталоге ~/seaf-workspace.

⁠Шаг 2. Запуск контейнера

Запустите контейнер SEAF ArchTool с помощью Docker CLI:

docker run -d \
  --name seaf-archtool \
  -p 8080:3030 \
  -v ~/seaf-workspace:/var/www/public/workspace:ro \
  -e VUE_APP_DOCHUB_BACKEND_PORT=3030 \
  -e VUE_APP_DOCHUB_ROOT_MANIFEST=workspace/root.yaml \
  -e VUE_APP_DOCHUB_APPEND_DOCHUB_DOCS=y \
  seaf/seaf-archtool-core:latest

Параметры команды:

• --name seaf-archtool - имя контейнера
• -p 8080:3030 - пробрасываем порт 3030 из контейнера на порт 8080 хоста
• -v ~/seaf-workspace:/var/www/public/workspace:ro - монтируем каталог с манифестами в режиме read-only
• -e VUE_APP_DOCHUB_ROOT_MANIFEST=workspace/root.yaml - указываем путь к корневому манифесту (относительно /var/www/public/)
• -e VUE_APP_DOCHUB_APPEND_DOCHUB_DOCS=y - включаем встроенную документацию DocHub

Важно: Путь ~/seaf-workspace замените на фактический путь к вашему каталогу с манифестами. Если используете относительный путь, укажите его через $(pwd):

docker run -d \
  --name seaf-archtool \
  -p 8080:3030 \
  -v $(pwd)/workspace:/var/www/public/workspace:ro \
  -e VUE_APP_DOCHUB_BACKEND_PORT=3030 \
  -e VUE_APP_DOCHUB_ROOT_MANIFEST=workspace/root.yaml \
  -e VUE_APP_DOCHUB_APPEND_DOCHUB_DOCS=y \
  seaf/seaf-archtool-core:latest

⁠Шаг 3. Проверка статуса

Убедитесь, что контейнер запущен:

docker ps | grep seaf-archtool

Следите за логами запуска:

docker logs -f seaf-archtool

Портал готов к работе, когда в логах появится сообщение о запуске на порту 3030.

⁠Шаг 4. Открытие портала

Откройте в браузере:

http://localhost:8080

Вы должны увидеть интерфейс портала с тестовым документом в навигации.

⁠Работа с манифестами

Если вы добавите или измените файлы в каталоге ~/seaf-workspace, изменения подхватятся порталом при следующем обновлении данных.

Запрос на обновление данных порталом:

curl -X PUT http://localhost:8080/core/storage/reload

⁠Остановка и удаление контейнера

Остановить контейнер:

docker stop seaf-archtool

Удалить контейнер:

docker rm seaf-archtool

Или остановить и удалить одной командой:

docker rm -f seaf-archtool

⁠Перезапуск с новыми настройками

Если нужно изменить параметры (например, порт или путь к манифестам):

# Удаляем старый контейнер
docker rm -f seaf-archtool

# Запускаем с новыми параметрами
docker run -d \
  --name seaf-archtool \
  -p 9090:3030 \
  -v ~/другой-путь:/var/www/public/workspace:ro \
  -e VUE_APP_DOCHUB_BACKEND_PORT=3030 \
  -e VUE_APP_DOCHUB_ROOT_MANIFEST=workspace/root.yaml \
  -e VUE_APP_DOCHUB_APPEND_DOCHUB_DOCS=y \
  seaf/seaf-archtool-core:latest

⁠Дополнительные настройки

⁠Использование конкретной версии образа

Вместо latest можно указать конкретную версию:

docker run -d \
  --name seaf-archtool \
  -p 8080:3030 \
  -v ~/seaf-workspace:/var/www/public/workspace:ro \
  -e VUE_APP_DOCHUB_BACKEND_PORT=3030 \
  -e VUE_APP_DOCHUB_ROOT_MANIFEST=workspace/root.yaml \
  -e VUE_APP_DOCHUB_APPEND_DOCHUB_DOCS=y \
  seaf/seaf-archtool-core:3.24.0

⁠Отключение встроенной документации DocHub

Если не нужна встроенная документация:

-e VUE_APP_DOCHUB_APPEND_DOCHUB_DOCS=n

⁠Изменение порта на хосте

Для запуска на порту 3000 (вместо 8080):

-p 3000:3030

Затем открывайте http://localhost:3000

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

⁠Порт 8080 уже занят

Проверьте, что порт свободен:

lsof -i :8080

Если порт занят, используйте другой порт, например 8081:

docker run -d --name seaf-archtool -p 8081:3030 ...

⁠Контейнер не запускается

Проверьте логи:

docker logs seaf-archtool

Убедитесь, что путь к workspace указан корректно и существует на хосте.

⁠Манифесты не отображаются

Проверьте:

1. Путь к workspace правильно смонтирован:

   docker exec seaf-archtool ls -la /var/www/public/workspace
   

   Copy

2. Файл root.yaml существует и читается:

   docker exec seaf-archtool cat /var/www/public/workspace/root.yaml
   

   Copy

3. Путь в переменной VUE_APP_DOCHUB_ROOT_MANIFEST указан без начального слеша (правильно: workspace/root.yaml, неправильно: /workspace/root.yaml)

⁠Образ не скачивается

Если Docker не может скачать образ, попробуйте скачать его явно:

docker pull seaf/seaf-archtool-core:latest

⁠Автоматический запуск при загрузке системы

⁠Docker с флагом --restart

Добавьте флаг --restart=always к команде запуска:

docker run -d \
  --name seaf-archtool \
  --restart=always \
  -p 8080:3030 \
  -v ~/seaf-workspace:/var/www/public/workspace:ro \
  -e VUE_APP_DOCHUB_BACKEND_PORT=3030 \
  -e VUE_APP_DOCHUB_ROOT_MANIFEST=workspace/root.yaml \
  -e VUE_APP_DOCHUB_APPEND_DOCHUB_DOCS=y \
  seaf/seaf-archtool-core:latest

Контейнер будет автоматически перезапускаться при перезагрузке системы или падении.

⁠Systemd service (Linux)

Создайте файл /etc/systemd/system/seaf-archtool.service:

[Unit]
Description=SEAF ArchTool Container
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/bin/docker run -d --name seaf-archtool -p 8080:3030 -v /home/user/seaf-workspace:/var/www/public/workspace:ro -e VUE_APP_DOCHUB_BACKEND_PORT=3030 -e VUE_APP_DOCHUB_ROOT_MANIFEST=workspace/root.yaml -e VUE_APP_DOCHUB_APPEND_DOCHUB_DOCS=y seaf/seaf-archtool-core:latest
ExecStop=/usr/bin/docker stop seaf-archtool
ExecStopPost=/usr/bin/docker rm seaf-archtool

[Install]
WantedBy=multi-user.target

Замените /home/user/seaf-workspace на ваш путь. Затем:

sudo systemctl daemon-reload
sudo systemctl enable seaf-archtool
sudo systemctl start seaf-archtool

⁠Что дальше

• Добавьте свои манифесты в каталог workspace и укажите их через импорты в root.yaml
• Когда потребуется совместная работа и хранение манифестов в Git - переходите к референсному развертыванию⁠
• Если нужен собственный PlantUML-сервер (для больших диаграмм или работы без интернета) - добавьте контейнер plantuml
• Описание всех переменных окружения - в справочнике⁠
• Для автоматического развертывания всех компонентов используйте unattended сценарий⁠