Посібник

На сторінці реєстрації вкажіть ім’я користувача, електронну пошту та пароль. Пошта знадобиться далі — на неї надійде код підтвердження.

Введіть код, який надійшов на вказану адресу.

У розділі «Мій кабінет» доступні перегляд основних даних облікового запису, зміна пароля, генерація ліцензійного ключа, надсилання повідомлення про помилку, а за наявності активної підписки — завантаження актуальної версії локального середовища.

Підписка відкриває доступ до всіх можливостей платформи. Її поточний статус відображається у вікні з даними облікового запису.

Доступ до ліцензійного ключа має лише власник підписки.

Перейдіть у розділ «Організації», натисніть «Створити організацію» та вкажіть її назву.

Після цього можна запросити учасника — йому надійде запит на вступ до організації.

• якщо особа вже має обліковий запис на порталі — запрошення надходить у сповіщення;
• якщо облікового запису ще немає — лист надходить на електронну пошту, зазвичай у теку «Промоакції».

Натисніть «Згенерувати».

Якщо якась сесія більше не потрібна, її можна відв’язати в кабінеті.

Якщо ви змінюєте пароль у кабінеті кнопкою «Змінити пароль», ліцензійний ключ залишається чинним.

Натисніть «Забули пароль?» і введіть свою пошту.

На пошту надійде лист для відновлення пароля.

Далі потрібно ввести новий пароль.

Якщо під час роботи виявлено помилку, надішліть повідомлення через відповідну форму особистого кабінету: опишіть, що сталося, і за потреби прикріпіть знімок екрана.

Після розгляду звернення адміністратор може надати відповідь — вона відображається в тому самому розділі кабінету.

• Windows 10 (64-розрядна) або новіша, macOS 12 або новіша;
• щонайменше 8 ГБ оперативної пам’яті, рекомендовано 16 ГБ;
• щонайменше 20 ГБ вільного місця на диску;
• доступ до Інтернету — потрібен для активації ліцензії.

Docker Desktop — основна програма, без якої локальне середовище не працює: саме вона запускає всі служби платформи.

Windows. Завантажте інсталятор зі сторінки docs.docker.com/desktop/install/windows-install/ і запустіть його. Залиште увімкненим пункт «Use WSL 2 instead of Hyper-V». Після встановлення перезавантажте комп’ютер — без цього компонент WSL 2 не активується.

macOS. Спочатку перевірте тип процесора: меню Apple → «Про цей Mac». Для Apple M1—M4 потрібна версія «Apple Silicon», для Intel — «Intel Chip». Завантажте відповідний файл .dmg зі сторінки docs.docker.com/desktop/install/mac-install/ і перетягніть Docker у теку «Програми».

Запустіть Docker Desktop і дочекайтеся готовності: індикатор у вигляді кита припинить анімацію, а в самій програмі з’явиться напис «Engine running».

Відкрийте Settings → Resources і встановіть щонайменше 8 ГБ оперативної пам’яті.

Там само відкрийте Settings → Resources → File Sharing і додайте диск або теку, де зберігатимуться пакет і реєстр — наприклад, C:\ у Windows.

Git Bash — командна оболонка, у якій команди з цього посібника виконуються без змін. У стандартному командному рядку Windows вони працюють не завжди.

Завантажте Git для Windows зі сторінки git-scm.com/download/win і встановіть — параметри можна залишити за замовчуванням. Переконайтеся, що увімкнено пункт «Git Bash Here»: він додає запуск оболонки з контекстного меню теки.

Потрібен, щоб створювати та редагувати регламенти реєстру. Якщо ви не плануєте розробляти власні послуги, цей крок можна пропустити.

Завантажте редактор зі сторінки code.visualstudio.com — сайт визначить вашу систему сам. У Windows під час встановлення рекомендуємо увімкнути пункти «Add to PATH» і «Open with Code». У macOS розпакуйте архів і перетягніть програму в теку «Програми».

Відкрийте Git Bash (Windows) або «Термінал» (macOS) і виконайте:

docker --version
docker compose version

Обидві команди мають повернути номери версій. Якщо система повідомляє, що команду не знайдено, Docker Desktop не запущено або не встановлено.

У самому низу кабінету лежить архів із образами. Поруч видно версію, розмір і дату оновлення, а нижче — опис змін. Натисніть «Скачати».

У релізі два складники: саме локальне середовище та розширення для Visual Studio Code, розкладені по теках під кожну операційну систему.

• diaenginelocal-1.0.0.tar — локальне середовище: образи контейнерів і файли конфігурації, близько 942 МБ. Його треба розпакувати;
• win/ — розширення для Visual Studio Code на Windows;
• mac/ — те саме розширення для macOS.

Спершу перемістіть архів у кінцеву теку — наприклад, C:\diaenginelocal у Windows. Не розпаковуйте його в «Завантаженнях» або на робочому столі: довгі шляхи з пробілами та кириличними символами спричиняють помилки підключення тек.

Найпростіший спосіб — командою. Відкрийте Git Bash (Windows) або «Термінал» (macOS) у теці з архівом і виконайте:

tar -xzf diaenginelocal-1.0.0.tar.gz

Формат .tar.gz — це два шари: спочатку файли складаються в один файл .tar, потім він стискається в .gz. Тому програми-архіватори розпаковують його у два етапи, а команда tar — за один.

Спосіб 1 — команда tar. Встановлювати нічого не потрібно, вона вже є в системі. Порядок дій — у кроці 8.3. Це рекомендований спосіб.

Спосіб 2 — 7-Zip для Windows. Завантажте з 7-zip.org і встановіть. Далі натисніть на архів правою кнопкою миші → 7-Zip → «Розпакувати тут». Першого разу ви отримаєте файл diaenginelocal-1.0.0.tar — натисніть на нього правою кнопкою ще раз і розпакуйте так само. Аж тоді з’явиться тека з файлами.

Спосіб 3 — The Unarchiver для macOS. Безкоштовна програма з App Store: після встановлення достатньо двічі натиснути на архів.

«Headers Error» або «Warnings» наприкінці розпакування в 7-Zip. На результат не впливає — файли розпаковано повністю й правильно. Так виходить тому, що архів створено засобами Docker, а вони записують службові заголовки у форматі, який 7-Zip читає лише частково. Натисніть «Close» і працюйте далі. Щоб попередження не з’являлося, скористайтеся командою tar із кроку 8.3.

«Cannot open: No such file or directory» під час виконання tar. Команда виконується не в тій теці, де лежить архів. Перевірте, де ви перебуваєте, командою pwd, а вміст теки — командою ls. Якщо архів уже розпаковано програмою-архіватором, повторювати tar не потрібно.

«bash: copy: command not found». У Git Bash діють команди Unix, а не Windows. Замість copy використовуйте cp:

cp .env.example .env

Після відкриття архіву ви побачите теку release_1.1, а поруч із нею — теку __MACOSX. Усе потрібне лежить у release_1.1.

Усередині release_1.1 — дві теки й один архів:

• diaenginelocal-1.0.0.tar — локальне середовище, близько 942 МБ; саме його розпаковуємо далі;
• win/ — розширення для Visual Studio Code на Windows;
• mac/ — розширення для macOS;
• .DS_Store — ще один службовий файл macOS, ігноруйте його.

Це другий і останній рівень вкладення. Розпакуйте його так само, як і перший — командою tar або архіватором.

tar -xf diaenginelocal-1.0.0.tar

Поруч з’являться два елементи: тека diaenginelocal-1.0.0 і файл ._diaenginelocal-1.0.0 розміром 1 КБ.

Усередині теки кожен файл ніби подвоєно: поруч зі справжнім лежить однойменний із префіксом ._ і розміром 1 КБ.

Це та сама службова інформація macOS, що й тека __MACOSX: система записує її поруч із кожним файлом, коли пакує архів. На Windows вони не потрібні й ні на що не впливають.

Відрізнити просто — дивіться на розмір і на початок імені:

• docker-compose.yml, 13 КБ — справжній файл конфігурації;
• ._docker-compose.yml, 1 КБ — службовий двійник, не чіпайте;
• images.tar, близько 942 МБ — справжній файл з образами;
• ._images.tar, 1 КБ — теж двійник.

У теці лежить файл README — коротка технічна інструкція з розгортання.

Відкрити його можна будь-яким текстовим редактором — «Блокнот» у Windows, TextEdit у macOS або Visual Studio Code. Розширення .md означає лише розмітку тексту, це звичайний текстовий файл.

Робоча тека виглядає так:

• images.tar.gz — образи контейнерів, близько 942 МБ; деякі архіватори показують його як images.tar;
• docker-compose.yml — конфігурація запуску служб;
• .env.example — зразок файлу налаштувань; створювати з нього .env не обов’язково;
• postgres/ — сценарії ініціалізації бази даних;
• pgadmin/ — налаштування засобу адміністрування бази даних;
• README — та сама коротка інструкція.

Відкрийте Git Bash або «Термінал» у теці з розпакованим пакетом і виконайте:

gunzip -c images.tar.gz | docker load

Далі завантажте службові образи — вони не входять до пакета:

docker compose pull postgres redis minio minio-init pgadmin

docker compose up -d
docker compose ps

Перший запуск триває кілька хвилин: створюються бази даних, застосовуються службові процедури, запускається Camunda. Служби очікують одна одну самі.

У колонці статусу для postgres, redis, camunda, data-factory, user-service, api-gateway і log-viewer має з’явитися значення (healthy).

Відкрийте http://localhost:3000. Застосунок попросить ліцензійний ключ — той самий, який ви згенерували на порталі. Введіть його та натисніть «Активувати».

Проходять через портал із перевіркою ліцензії:

• pgAdmin — :5050
• Camunda — :8085
• перегляд журналів — :8092
• консоль MinIO — :9011

docker compose down      # дані зберігаються

docker compose down -v   # видаляє всі дані та стан ліцензії

Після першого запуску середовище працює, але послуг у кабінетах немає, а тека registry-regulations порожня або містить лише кілька файлів. Це очікувана поведінка, а не помилка встановлення.

Реєстр — це набір регламентів: бізнес-процеси, форми, модель даних, ролі та інші файли, які визначають, які саме послуги надає ваша установа. Реєстр є вашими даними, а не частиною програми, тому він не входить до пакета й не може постачатися разом із ним.

Ознаки того, що реєстр ще не підключено:

• угорі сторінки видно повідомлення «Реєстр не налаштовано»;
• у кабінетах немає жодної доступної послуги;
• на панелі адміністратора лічильники показують нулі — наприклад, bpmn 0 · forms 0 · data-model 0.

Розмістіть теку з реєстром на диску до початку налаштування. Усередині очікується така структура:

my-registry/
├── bpmn/           бізнес-процеси (.bpmn)
├── forms/          форми (.json)
├── data-model/     модель даних (.xml)
├── excerpts/       шаблони витягів
├── roles/          ролі користувачів
└── ...             інші каталоги регламенту

Вимоги до теки:

• її потрібно додати у Docker Desktop → Settings → Resources → File Sharing — інакше всередині контейнера тека буде порожньою;
• потрібні права на запис: панель адміністратора виконує в ній службові операції;
• уникайте шляхів із пробілами та кириличними символами.

У лівій нижній частині сторінки локального середовища натисніть «Адміністрування». Перейти туди можна й за посиланням у самому повідомленні «Реєстр не налаштовано».

На панелі адміністратора знайдіть розділ «Реєстр» унизу сторінки. Натисніть «Обрати папку…» та виберіть теку з реєстром — або введіть шлях у поле вручну й натисніть «Зберегти шлях».

Формат шляху залежить від системи:

• Windows — /run/desktop/mnt/host/c/diaengine/my-registry;
• macOS — /Users/ім’я-користувача/registries/my-registry.

Натисніть «Зібрати (застосувати)». Служби буде перезапущено з підключеною текою реєстру — це триває кілька хвилин.

Після завершення в рядку «Поточна папка» мають з’явитися ненульові лічильники — наприклад, bpmn 12 · forms 34 · data-model 8, — а повідомлення «Реєстр не налаштовано» зникнути.

У розділі «Користувачі реєстру» натисніть «Управління користувачами».

Оберіть кабінет — «Громадянин» або «Посадовець» — і натисніть «Додати користувача». Заповніть дані та призначте ролі відповідно до регламенту вашого реєстру.

Реєстр підключено правильно, якщо виконуються всі умови:

• повідомлення «Реєстр не налаштовано» більше не з’являється;
• у розділі «Реєстр» лічильники показують фактичну кількість файлів;
• створено щонайменше одного користувача;
• на панелі адміністратора кількість визначених процесів відмінна від нуля.

Після входу в кабінеті доступні послуги — відповідно до ролей, призначених користувачу.

Тут відображаються послуги, закріплені за вами, а також ті, які ви вже надали.

Усі доступні для цієї посади послуги зібрані у вкладці «Доступні послуги».

Завершити сесію можна і з локальної версії, і з кабінету на порталі — відв’язавши копію в блоці ліцензійного ключа.

В архіві, який ви завантажили з кабінету, лежать два розширення — по одному на кожну операційну систему. Вони розкладені по теках: win — для Windows, mac — для macOS. Обидва мають розширення .vsix.

Відкрийте теку, що відповідає вашій системі, і візьміть файл звідти. Другу теку можна не чіпати — вона потрібна тим, хто працює на іншій платформі.

• Windows — тека win, файл dia-engine-ide-win32-x64-<версія>.vsix;
• macOS на процесорах Apple M1—M4 — тека mac, файл dia-engine-ide-darwin-arm64-<версія>.vsix;
• macOS на процесорах Intel — тека mac, файл dia-engine-ide-darwin-x64-<версія>.vsix.

Щоб визначити тип процесора на Mac, відкрийте меню Apple → «Про цей Mac»: у рядку «Чип» або «Процесор» буде зазначено Apple M1—M4 або Intel.

У VS Code відкрийте вкладку Extensions — значок із квадратами на лівій панелі або Ctrl + Shift + X (у macOS — Cmd + Shift + X). Натисніть три крапки вгорі панелі та оберіть «Install from VSIX…».

Знайдіть файл .vsix для вашої системи та натисніть «Install». Після встановлення VS Code запропонує перезавантажити вікно — погодьтеся.

Переконатися, що все вдалося, можна на вкладці Extensions у розділі Installed: у переліку має бути «Dia Engine IDE».

• візуальний конструктор бізнес-процесів із панеллю властивостей і готовими шаблонами елементів;
• конструктор форм із понад 40 спеціалізованими компонентами та режимом попереднього перегляду;
• перевірка файлів на помилки — посилання на форми, унікальність ключів, структура моделі даних;
• запуск і зупинка служб, публікація процесів і форм, запуск міграцій бази даних;
• дерева файлів реєстру на окремій панелі та стан служб у рядку стану.

Команди викликаються через палітру: Ctrl + Shift + P (у macOS — Cmd + Shift + P), усі починаються з «Dia:».

Відкрийте теку з реєстром через File → Open Folder. Розширення визначить структуру само й покаже на панелі «Dia Engine» дерева процесів, форм і моделі даних. Натискання на файл відкриває його у відповідному редакторі.

Панель відкривається з посилання «Адміністрування» в лівому нижньому куті. Вона потрібна у двох випадках: коли ви підключаєте або міняєте реєстр і коли зміни в регламенті не з’явилися в кабінетах.

Згори видно зведення: скільки визначено процесів, скільки з них виконується просто зараз, скільки відкритих задач і скільки форм у кеші. Поруч — стан служб: «Всі сервіси активні» означає, що середовище готове до роботи.

Найлегша і найчастіша дія. Перечитує файли реєстру й підхоплює зміни, не чіпаючи ані бази даних, ані запущених процесів. Саме з неї варто починати, коли ви щойно відредагували регламент і хочете побачити результат.

Коли ви знаєте, що саме змінили, не потрібно оновлювати все. Поруч стоять три кнопки, кожна перечитує свою частину регламенту.

BPMN процеси — публікує схеми бізнес-процесів із теки bpmn. Натискайте після зміни ходу процесу.

Форми — перечитує форми з теки forms. Натискайте після зміни полів, підказок або перевірок у формі.

Авторизація — перечитує ролі та права доступу. Натискайте після зміни файлів у теці roles: доки цього не зробити, посадовець не побачить щойно виданої йому послуги.

Застосовує до бази даних зміни, описані в теці data-model: нові таблиці, колонки, довідники. Наявні дані зберігаються — додається лише те, чого ще немає.

Створює структуру бази заново за поточною моделлю даних. Потрібна тоді, коли міграції не проходять — наприклад, після несумісної зміни в моделі, яку не можна застосувати поверх наявної структури.

Найважча дія: перезбирає все середовище з нуля — конфігурацію, процеси, форми, права та структуру бази. Це останній засіб, коли простіші дії не допомогли й незрозуміло, що саме зламалося.

Відкриває журнали всіх служб в окремій вкладці. Сюди варто зазирнути, коли щось не працює, а причина неочевидна: помилка майже завжди описана в журналі докладніше, ніж у повідомленні на екрані.

Окремий журнал саме про підключення реєстру: що прочитано, що опубліковано, на чому зупинилося. Перше місце, куди варто подивитися, якщо після «Зібрати (застосувати)» лічильники залишилися нульовими або послуги не з’явилися.

Нижче видно перелік служб — camunda, data-factory, redash, pgadmin, minio — із поточним станом і приблизним обсягом пам’яті, який кожна займає. Службу можна зупинити або запустити кнопкою поруч.

Redash будує звіти та діаграми за даними реєстру: довільні запити до бази, таблиці, графіки, інформаційні панелі. Служба необов’язкова, тому в новому середовищі вона не запущена.

Вимкнена вона навмисно: Redash займає близько 300 МБ пам’яті й потрібен далеко не кожному. Якщо звіти не потрібні, лишайте як є — на роботу решти платформи це не впливає.

Щоб запустити, знайдіть картку redash у розділі «Керування сервісами» й натисніть кнопку відтворення праворуч.

Перший запуск триває довше за звичайний — служба створює власну базу даних. Коли вона підніметься, стан у картці зміниться на «Running», а нижче, у розділі «Стан компонентів», картка Redash покаже порт :5001, відповідь HTTP 200 і посилання «Redash UI».

Зупинити службу можна тією самою кнопкою в картці.

Після запуску Redash з’являється в кабінеті посадової особи — у розділі «Звіти» зліва. Натисніть «Відкрити Redash».

Той самий інтерфейс відкриває посилання «Redash UI» у розділі «Стан компонентів» на панелі адміністратора — це зручніше, коли ви вже там і не хочете повертатися до кабінету.

Верхній ряд відкриває службові інтерфейси платформи. Усі вони вже налаштовані, а логін і пароль зазначені просто на кнопці — у дужках після назви.

Відкриває базу даних: таблиці реєстру, їхній вміст, структуру. Сюди варто зазирнути, коли треба переконатися, що дані справді записалися.

Сховище файлів: усе, що користувачі прикріпили до заявок, і дистрибутиви. Тут видно самі файли та їхній розмір.

Показує процеси, які виконуються просто зараз: на якому кроці кожен, де зупинився, чи були помилки. Основний інструмент, коли послуга «зависла» й незрозуміло чому.

Перелік задач, які процеси створили для посадовців. Те саме, що людина бачить у своєму кабінеті, але без прив’язки до ролей — видно всі відразу.

Адміністрування самого рушія процесів: облікові записи, групи, права всередині Camunda.

Те саме, що й кнопка «Переглядач логів» нижче на панелі: журнали всіх служб з пошуком за текстом.

Повний перелік запитів, які приймає платформа: адреси, параметри, формат відповіді. Потрібен тому, хто пише інтеграцію із зовнішньою системою.

Повертає на головну сторінку локального середовища — до кабінетів громадянина та посадовця.

Відкриває перелік користувачів реєстру окремо для кабінету громадянина та кабінету посадовця. Тут їх створюють, редагують і призначають ролі.

Кнопка «Додати користувача» відкриває форму. Обов’язкових полів у ній немає жодного, окрім ролей: ім’я згенерується автоматично, якщо його не вписати.

• Ім’я користувача — під ним людина входитиме; якщо лишити порожнім, буде згенеровано автоматично;
• ПІБ — відображається в інтерфейсі та у витягах;
• РНОКПП — десять цифр, ідентифікатор фізичної особи;
• ЄДРПОУ — вісім або десять цифр, потрібен для представника юридичної особи;
• Ролі — визначають, які послуги побачить користувач; перелік формується з файлів вашого реєстру;
• Атрибути — додаткові дані, якщо їх вимагає регламент.

Порядок від найлегшої дії до найважчої — переходьте до наступної, лише якщо попередня не допомогла:

• зміни в регламенті не з’явилися — «Оновити конфігурацію»;
• змінювали тільки процеси, форми або ролі — відповідна кнопка з розділу 12.3;
• додали таблиці чи поля в модель даних — «Liquibase міграції»;
• незрозуміла помилка — «Логи збірки реєстру», потім «Переглядач логів»;
• міграції не проходять — «Перебудувати базу» (дані буде втрачено);
• нічого з переліченого не допомогло — «Повна перебудова» (дані буде втрачено).

Стан служб:

docker compose ps

Журнал окремої служби:

docker compose logs -f api-gateway

Журнали можна дивитися і у вебінтерфейсі на порту 8092 — там зручніше шукати за текстом.

Копія всіх баз даних одним файлом:

docker compose exec postgres pg_dumpall -U registry > backup.sql

• «Реєстр не налаштовано» або немає жодної послуги — реєстр не підключено, див. розділ 9;
• тека реєстру всередині контейнера порожня — теку не додано у Docker Desktop -> Settings -> Resources -> File Sharing або шлях вказано у форматі Windows замість Unix;
• camunda не переходить у стан healthy — замало оперативної пам’яті, збільште до 8 ГБ і більше;
• «port is already allocated» — порт зайнято іншою програмою; завершіть її роботу або змініть порт у .env;
• «Ліцензійний ключ відкликано в кабінеті» — ключ анульовано, згенеруйте новий на порталі;
• повідомлення про невідповідність платформи образу — завантажено образи попередньої версії; виконайте docker compose down, видаліть їх і завантажте з пакета повторно;
• «docker: command not found» — Docker Desktop не запущено або не встановлено, див. розділ 7.

Надішліть повідомлення про помилку з кабінету на порталі (розділ 6). Додайте до нього результат виконання двох команд — так ми побачимо, на якому саме етапі все зупинилося:

docker compose ps
docker compose logs --tail=200