Розгортання системи K2 ERP Python для розробників

Розгортання системи K2 ERP Python для розробників — це інструкція з локального запуску робочого проєкту K2 ERP, підключення середовища розробки, налаштування Git, роботи з компонентами та публікації оновлень.

Документ призначений для розробників, які підключаються до Python-версії K2 ERP, працюють із компонентами системи, вносять зміни в код і передають нові версії на сервер оновлень.

Коротко. Щоб почати роботу, потрібно скопіювати проєкт, виконати первинне налаштування через first_run, запустити систему локально, підключити PyCharm, налаштувати Git і працювати з компонентами через репозиторії або скрипт auto_update.

Загальна схема роботи

Розгортання локального середовища K2 ERP складається з кількох основних етапів:

копіювання робочого проєкту з віддаленого сервера;
первинне налаштування локального середовища;
запуск системи;
відкриття проєкту в PyCharm;
налаштування Python Interpreter;
встановлення та налаштування Git;
підключення репозиторіїв компонент;
коміт і публікація змін;
підготовка компонент до сервера оновлень;
тестування на тестових доменах.

1. Копіювання проєкту і перший запуск

Спочатку потрібно скопіювати існуючий робочий проєкт K2 ERP з віддаленого сервера по FTP.

Після копіювання потрібно перейти в каталог проєкту:

/K2CloudERP

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

Linux

bash first_run.sh

Windows

./first_run.bat

Після цього потрібно відкрити файл налаштувань:

/K2CloudERP/cfg/k2/k2/k2cfg.py

Для локального запуску змінити параметр:

domain_protocol = "https"

на:

domain_protocol = "http"

Після налаштування можна запускати застосунок.

Linux

bash run.sh

Windows

./run.bat

Важливо. Для локальної розробки потрібно перевірити, що domain_protocol змінено з https на http. Інакше локальний запуск може працювати некоректно.

2. Встановлення PyCharm

Для розробки використовується середовище PyCharm.

Можна використовувати PyCharm Community або іншу редакцію, яка підходить для роботи з Python-проєктами.

Встановлення PyCharm у Linux через snap

sudo rm /etc/apt/preferences.d/nosnap.pref
sudo apt update
sudo apt install snapd
sudo snap install pycharm-community --classic
pycharm-community

Встановлення PyCharm у Linux з архіву

Завантажити PyCharm можна з офіційної сторінки:

https://www.jetbrains.com/pycharm/download/?section=linux

Після завантаження потрібно розпакувати архів, перейти в каталог bin і запустити:

./pycharm.sh

Якщо під час запуску виникає помилка, потрібно встановити JRE/JDK:

sudo apt update
sudo apt install default-jdk

Встановлення PyCharm у Windows

Завантажити PyCharm можна з офіційної сторінки:

https://www.jetbrains.com/pycharm/download/?section=windows

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

3. Відкриття проєкту в PyCharm

Після встановлення PyCharm потрібно відкрити локально скопійований проєкт K2 ERP.

У PyCharm потрібно налаштувати Python Interpreter для поточного проєкту.

Порядок дій:

відкрити проєкт у PyCharm;
у правому нижньому куті вибрати Python Interpreter;
натиснути Add New Interpreter;
у полі Location вказати шлях до локальної папки venv;
у полі Base Interpreter вказати шлях до виконуваного Python-файлу з поточного віртуального середовища.

Приклад шляху:

../K2CloudERP/venv/bin/python3.12

Для Windows шлях може мати вигляд:

..\K2CloudERP\venv\Scripts\python.exe

Після налаштування інтерпретатора проєкт можна запускати в режимі debug або з консолі PyCharm.

Запуск з консолі PyCharm

Linux:

bash run.sh

Windows:

./run.bat

Ручна активація віртуального середовища

Linux:

source venv/bin/activate

Windows:

.\venv\Scripts\activate

4. Встановлення Git

Git потрібен для роботи з репозиторіями компонент K2 ERP, отримання оновлень, комітів і публікації змін.

Linux

sudo apt update
sudo apt install git

Windows

Завантажити Git можна зі сторінки:

https://git-scm.com/downloads/win

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

5. Базове налаштування Git

Після встановлення Git потрібно вказати ім’я користувача та email.

git config --global user.name "Ваше Ім'я"
git config --global user.email "ваша_електронна_пошта@example.com"

6. Налаштування SSH-ключа

Для роботи з віддаленими репозиторіями може використовуватися SSH-авторизація.

Створення SSH-ключа:

ssh-keygen -t rsa -b 4096 -C "ваша_електронна_пошта@example.com"

Запуск ssh-agent:

eval "$(ssh-agent -s)"

Додавання ключа:

ssh-add ~/.ssh/id_rsa

Перегляд публічного ключа:

cat ~/.ssh/id_rsa.pub

Отриманий публічний ключ потрібно скопіювати та додати у віддалений Git-репозиторій.

Практична порада. Для стабільної роботи з Git краще налаштувати SSH-доступ один раз і далі працювати з репозиторіями без постійного введення логіна та пароля.

7. Підключення компонент через auto_update

Для роботи зі списком компонент можна використовувати скрипт auto_update.

Каталог зі скриптом потрібно скопіювати в корінь проєкту на рівень із файлом:

app.py

Репозиторій скрипта:

https://git.corp2.eu/k2erp/python/k2/base/client/auto_update

Після копіювання потрібно перейти в каталог:

cd auto_update

У файлі:

settings.py

потрібно додати в словник ключі потрібних компонент.

Повний приклад доступний у файлі:

settings_example.py

Для клонування актуальних версій компонент виконується команда:

python git_cmd.py clone

Ця команда клонує компоненти та перейменовує каталоги поточних версій компонент.

8. Підключення однієї компоненти вручну

Якщо потрібно підключити лише одну компоненту вручну, потрібно перейти в каталог потрібної компоненти.

Наприклад:

cd components/k2site

Ініціалізація Git у поточній директорії:

git init

Створення локальної гілки main і перемикання на неї:

git checkout -b main

Перемикання на іншу локальну гілку, якщо потрібно:

git checkout master

Додавання віддаленого репозиторію:

git remote add origin http://git.corp2.eu/k2erp/python/k2/base/site/k2site.git

Перевірка віддаленого репозиторію:

git remote -v

Отримання даних із віддаленого репозиторію без зміни поточної гілки:

git fetch origin

Отримання змін і автоматичне об’єднання з локальною гілкою:

git pull origin main

Перевірка статусу:

git status

9. Коміт змін через auto_update

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

cd auto_update

Клонування компонент:

python git_cmd.py clone

Перевірка статусу:

python git_cmd.py status

Коміт змін:

python git_cmd.py commit

Отримання змін із віддаленого сервера:

python git_cmd.py pull

Публікація змін у віддалений репозиторій:

python git_cmd.py push

10. Коміт змін вручну

Після внесення змін у коді потрібно перевірити статус:

git status

Додати зміни:

git add .

Створити коміт:

git commit -m "Назва коміту"

Відправити зміни у віддалений репозиторій:

git push

Під час подальшої роботи потрібно регулярно отримувати зміни з віддаленого репозиторію:

git pull

Важливо. Перед комітом потрібно перевірити git status, щоб випадково не відправити службові файли, локальні налаштування, тимчасові файли або зайві каталоги.

11. Налаштування завантаження компонент на сервер оновлень

Для публікації компонент на сервер оновлень використовується конфігурація в каталозі:

builder/config

У файлі:

component-list.txt

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

Приклад:

components/k2update
components/k2adm
components/k2site

У каталозі:

builder/config/ignore

потрібно створити файл із назвою компоненти та вказати файли або папки, які не потрібно завантажувати.

Приклад файлу:

k2site.txt

Приклад вмісту:

__pycache__
.gitignore
.git
ej2.min.js

У файлі:

token.txt

потрібно вказати токен доступу до сервера оновлень.

12. Підготовка нової версії компоненти

Для створення нової версії компоненти потрібно змінити версію у файлі:

setup.py

Файл знаходиться в корені каталогу компоненти.

Приклад:

version = "2.0.4.43"
version_type = "stable"

Для тестової версії можна використовувати:

version_type = "testing"

Після зміни версії потрібно додати опис змін у файл:

history.txt

Файл також знаходиться в корені каталогу компоненти.

Приклад рядка:

2.0.4.43 - додавання додаткового поля у форму реєстрації

13. Завантаження компоненти в систему оновлення

Після підготовки версії потрібно перейти в корінь застосунку, на рівень із файлом:

app.py

Приклад переходу:

cd k2

Завантаження компонент, зазначених у файлі builder/config/component-list.txt, виконується командою:

python k2update_push.py

14. Тестування на deb1–deb3

Після завантаження нової версії потрібно оновити змінені компоненти на тестових доменах:

deb1
deb2
deb3

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

Тестування має підтвердити, що:

компонента оновилася коректно;
новий функціонал працює;
старий функціонал не зламався;
помилки не відтворюються;
зміни можна передавати далі.

Контрольний чек-лист розгортання

№	Перевірка
1	Проєкт скопійовано з віддаленого сервера по FTP
2	Виконано `first_run.sh` або `first_run.bat`
3	У `k2cfg.py` змінено `domain_protocol` з `https` на `http`
4	Проєкт запускається через `run.sh` або `run.bat`
5	У PyCharm налаштовано Python Interpreter на локальне `venv`
6	Встановлено та налаштовано Git
7	Налаштовано SSH або інший спосіб авторизації в репозиторії
8	Підключено потрібні компоненти вручну або через `auto_update`
9	Перевірено роботу `git status`, `git pull`, `git push`
10	Налаштовано `builder/config/component-list.txt`
11	Налаштовано файли `ignore` для компонент
12	Додано токен у `token.txt`
13	Оновлено версію компоненти в `setup.py`
14	Додано опис змін у `history.txt`
15	Виконано `python k2update_push.py`
16	Оновлено компоненти на `deb1`–`deb3`
17	Перевірено функціонал після оновлення

Типові помилки

Помилка	Причина	Що перевірити
Проєкт не запускається локально	Не виконано `first_run` або неправильно налаштоване середовище	Повторити `first_run`, перевірити `venv`
Локальний запуск відкривається через HTTPS	Не змінено `domain_protocol`	Перевірити `k2cfg.py`
PyCharm не бачить залежності	Не вибрано правильний Python Interpreter	Перевірити шлях до `venv`
Git не пушить зміни	Не налаштовано авторизацію або немає прав	Перевірити SSH-ключ, remote URL і доступи
На сервер оновлень потрапляють зайві файли	Не налаштовано `ignore`	Перевірити файл компоненти в `builder/config/ignore`
Компонента не оновлюється на тестовому домені	Не змінено версію або не завантажено оновлення	Перевірити `setup.py`, `history.txt`, `k2update_push.py`

Коротко

Питання	Відповідь
З чого почати?	Скопіювати проєкт, виконати `first_run`, змінити `domain_protocol` і запустити `run`
Яке середовище розробки використовується?	PyCharm
Де налаштовується локальний Python?	У Python Interpreter через локальний `venv`
Як працювати з компонентами?	Через `auto_update` або вручну через Git
Як публікувати зміни?	Через Git-коміт і `python k2update_push.py`
Де тестувати оновлення?	На тестових доменах `deb1`, `deb2`, `deb3`

Див. також